docc validation needs JAVA_HOME to be set up

Author: ktoso

.github/actions/prepare_env/action.yml

@@ -26,9 +26,9 @@ runs:
         elif [[ -n "$JAVA_HOME_24_ARM64" ]]; then
           echo "JAVA_HOME_24=$JAVA_HOME_24_ARM64" >> $GITHUB_ENV
         fi
-    - name: Check Java environment
-      shell: bash
-      run: ./gradlew -q javaToolchains
+      # - name: Check Java environment
+      #  shell: bash
+      #  run: ./gradlew -q javaToolchains
     - name: Cache local SwiftPM repository
       if: matrix.os_version == 'jammy'
       uses: actions/cache@v4

.github/workflows/pull_request.yml

@@ -13,6 +13,34 @@ jobs:
       # FIXME: Something is off with the format task and it gets "stuck", need to investigate
       format_check_enabled: false
       license_header_check_project_name: Swift.org
+      # Since we need JAVA_HOME to be set up for building the project and depending on a different workflow won't
+      # give us that, we disable the checking and make a separate job that performs docs validation
+      docs_check_enabled: false
+
+  # This replicates 'docs-check' from https://github.com/swiftlang/github-workflows/blob/main/.github/workflows/soundness.yml
+  # because we need to set up environment so we can build the SwiftJava project (including Java runtime/dependencies).
+  soundness-docs:
+    name: Documentation check
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: true
+      matrix:
+        swift_version: ['6.1.2']
+        jdk_vendor: ['corretto']
+    env:
+      ADDITIONAL_DOCC_ARGUMENTS: ''
+    steps:
+      - uses: actions/checkout@v4
+      - name: Prepare CI Environment
+        uses: ./.github/actions/prepare_env
+      - name: Install Swiftly 
+        run: ./.github/scripts/install_swiftly.sh
+        env:
+          SWIFT_VERSION: "${{ matrix.swift_version }}"
+      - name: Run documentation check
+        run: |
+          which curl || (apt -q update && apt -yq install curl)
+          curl -s --retry 3 https://raw.githubusercontent.com/swiftlang/github-workflows/refs/heads/main/.github/workflows/scripts/check-docs.sh | bash
 
   test-java:
     name: Test (Java) (${{ matrix.os_version }} swift:${{ matrix.swift_version }} jdk:${{matrix.jdk_vendor}})

Sources/JavaKit/JavaKit.docc/index.md renamed to Sources/JavaKit/Documentation.docc/JavaKit.md

@@ -1,4 +1,4 @@
-# ``JavaKit``
+# JavaKit
 
 Library and tools to make it easy to use Java libraries from Swift using the Java Native Interface (JNI).
 

Sources/SwiftJavaDocumentation/Documentation.docc/SwiftPMPlugin.md

@@ -1,6 +1,6 @@
 # SwiftJava SwiftPM Plugin
 
-The `SwiftJavaPlugin` automates <doc:SwiftJavaCommandLineTool> invocations during the build process.
+The `SwiftJavaPlugin` automates `swift-java` command line tool invocations during the build process.
 
 ## Installing the plugin
 

Sources/SwiftJavaDocumentation/Documentation.docc/index.md

@@ -1,4 +1,4 @@
-# ``SwiftJavaDocumentation``
+# SwiftJavaDocumentation
 
 @Metadata {
   @TechnologyRoot
@@ -32,10 +32,3 @@ which is a quick overview of all the features and approaches offered by SwiftJav
 - <doc:SwiftJavaCommandLineTool>
 - <doc:SwiftPMPlugin>
 
-### Using Java from Swift
-
-- JavaKit
-
-### Using Swift from Java
-
-- SwiftKitSwift