docs: build multiversion Javadocs in parallel with matching JDKs

Docs publishing runs make -C docs multiversion, but PR docs CI only ran make -C docs test. That left the publish-only multiversion and Javadoc path uncovered before merge.

Install Java 8 alongside Java 11 in the docs workflows and make the multiversion post-build helper select Java 8 for historical scylla-* and tag refs while keeping Java 11 for the current docs build. The helper still runs each checked-out ref's own docs/_utils/javadoc.sh, so older docs use their branch-local Maven and docs configuration.

Run make -C docs multiversion in PR CI and include docs workflow files in the docs workflow path filters so CI changes are validated before publishing.

Build multiversion refs with a repo-local parallel runner. It calculates version-level parallelism from os.cpu_count(), caps it at 8 workers, builds each version in an isolated temporary output root to avoid shared Sphinx theme asset races, then publishes completed outputs serially.

Give each version build its own temporary Maven local repository through MAVEN_OPTS so parallel historical Javadoc builds do not race on shared snapshot metadata.

Also make the current branch Javadoc script deterministic: skip install-time Javadoc attachment during the preparatory install, keep Maven parallelism with -T 1C, accept the current core/target/reports/apidocs output location with fallback to core/target/site/apidocs, and fail clearly when generated output is missing or empty.

Author: dkropachev

.github/workflows/docs-pages.yml

@@ -8,6 +8,8 @@ on:
     - scylla-4.x
     - 'scylla-**'
     paths:
+    - '.github/workflows/docs-pages.yml'
+    - '.github/workflows/docs-pr.yml'
     - 'docs/**'
     - 'faq/**'
     - 'manual/**'
@@ -36,6 +38,12 @@ jobs:
         with:
           python-version: '3.13'
 
+      - name: Set up JDK 8 for historical docs
+        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
+        with:
+          java-version: '8'
+          distribution: 'temurin'
+
       - name: Set up JDK 11
         uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
         with:

.github/workflows/docs-pr.yml

@@ -10,6 +10,8 @@ on:
     branches:
     - scylla-4.x
     paths:
+    - '.github/workflows/docs-pages.yml'
+    - '.github/workflows/docs-pr.yml'
     - 'docs/**'
     - 'faq/**'
     - 'manual/**'
@@ -31,6 +33,12 @@ jobs:
         with:
           python-version: '3.13'
 
+      - name: Set up JDK 8 for historical docs
+        uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
+        with:
+          java-version: '8'
+          distribution: 'temurin'
+
       - name: Set up JDK 11
         uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
         with:
@@ -45,3 +53,6 @@ jobs:
 
       - name: Build docs
         run: make -C docs test
+
+      - name: Build published docs
+        run: make -C docs multiversion

docs/_utils/javadoc.sh

@@ -1,17 +1,34 @@
 #!/bin/bash
+set -euo pipefail
 
 # Install dependencies
-mvn install -DskipTests -T 1C
+mvn install -DskipTests -Dmaven.javadoc.skip=true -T 1C
 
 # Define output folder
 OUTPUT_DIR="docs/_build/dirhtml/api"
-if [[ "$SPHINX_MULTIVERSION_OUTPUTDIR" != "" ]]; then
+if [[ "${SPHINX_MULTIVERSION_OUTPUTDIR:-}" != "" ]]; then
     OUTPUT_DIR="$SPHINX_MULTIVERSION_OUTPUTDIR/api"
     echo "HTML_OUTPUT = $OUTPUT_DIR" >> doxyfile
 fi
 
 # Generate javadoc
 mvn javadoc:javadoc -T 1C
-[ -d $OUTPUT_DIR ] && rm -r $OUTPUT_DIR
+JAVADOC_SOURCE_DIR="core/target/site/apidocs"
+if [[ ! -d "$JAVADOC_SOURCE_DIR" && -d "core/target/reports/apidocs" ]]; then
+    JAVADOC_SOURCE_DIR="core/target/reports/apidocs"
+fi
+if [[ ! -d "$JAVADOC_SOURCE_DIR" ]]; then
+    echo "Javadoc output directory was not generated" >&2
+    exit 1
+fi
+shopt -s nullglob
+JAVADOC_FILES=("$JAVADOC_SOURCE_DIR"/*)
+if (( ${#JAVADOC_FILES[@]} == 0 )); then
+    echo "Javadoc output directory is empty" >&2
+    exit 1
+fi
+if [[ -d "$OUTPUT_DIR" ]]; then
+    rm -r "$OUTPUT_DIR"
+fi
 mkdir -p "$OUTPUT_DIR"
-mv -f core/target/site/apidocs/* $OUTPUT_DIR
+mv -f "${JAVADOC_FILES[@]}" "$OUTPUT_DIR"

docs/_utils/multiversion-javadoc.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+set -euo pipefail
+
+# sphinx-multiversion runs this script from each temporary checkout. This
+# branch-owned wrapper only selects the Java runtime; the actual Javadocs are
+# still generated by the checkout's own docs/_utils/javadoc.sh so historical
+# refs keep their branch-local docs and Maven configuration.
+
+version_name="${SPHINX_MULTIVERSION_NAME:-unknown}"
+
+if [[ "${version_name}" == scylla-* || "${version_name}" == tags/* ]]; then
+    if [[ -z "${JAVA_HOME_8_X64:-}" ]]; then
+        echo "JAVA_HOME_8_X64 is required to build historical docs for ${version_name}" >&2
+        exit 1
+    fi
+
+    export JAVA_HOME="$JAVA_HOME_8_X64"
+    export PATH="$JAVA_HOME/bin:$PATH"
+    echo "Using Java 8 for historical docs version ${version_name}"
+elif [[ -n "${JAVA_HOME_11_X64:-}" ]]; then
+    export JAVA_HOME="$JAVA_HOME_11_X64"
+    export PATH="$JAVA_HOME/bin:$PATH"
+    echo "Using Java 11 for ${version_name}"
+fi
+
+echo "Building Javadocs for ${version_name} with Java:"
+java -version
+
+bash -e ./docs/_utils/javadoc.sh

docs/_utils/multiversion.sh

@@ -1,5 +1,9 @@
-#! /bin/bash	
+#! /bin/bash
+set -euo pipefail
 
-cd .. && sphinx-multiversion docs/source docs/_build/dirhtml \
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+cd "$REPO_ROOT" && python "$SCRIPT_DIR/parallel_multiversion.py" docs/source docs/_build/dirhtml \
     --pre-build "bash -c \"(find . -mindepth 2 -name README.md -execdir mv '{}' index.md ';'; find . -mindepth 2 -name README.rst -execdir mv '{}' index.rst ';')\"" \
-    --post-build './docs/_utils/javadoc.sh'
+    --post-build "bash '$SCRIPT_DIR/multiversion-javadoc.sh'"