docs: build multiversion Javadocs with matching JDKs

.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" && sphinx-multiversion 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'"