docs: build historical multiversion docs with Java 8

.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,20 @@
 #!/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
+if [[ -d "$OUTPUT_DIR" ]]; then
+    rm -r "$OUTPUT_DIR"
+fi
 mkdir -p "$OUTPUT_DIR"
-mv -f core/target/site/apidocs/* $OUTPUT_DIR
+mv -f core/target/site/apidocs/* "$OUTPUT_DIR"

docs/_utils/multiversion.sh

@@ -1,5 +1,43 @@
-#! /bin/bash	
+#! /bin/bash
+set -euo pipefail
 
-cd .. && sphinx-multiversion docs/source docs/_build/dirhtml \
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+
+# sphinx-multiversion runs post-build commands from each temporary checkout.
+# Keep using that checkout's own docs/_utils/javadoc.sh and Maven config, but
+# select the Java runtime here so older refs build with the JDK they expect.
+POST_BUILD_JAVADOC='
+set -euo pipefail
+
+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
+
+output_dir="docs/_build/dirhtml/api"
+if [[ -n "${SPHINX_MULTIVERSION_OUTPUTDIR:-}" ]]; then
+    output_dir="${SPHINX_MULTIVERSION_OUTPUTDIR}/api"
+fi
+rm -rf "$output_dir"
+
+bash -e ./docs/_utils/javadoc.sh
+'
+
+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 -c '$POST_BUILD_JAVADOC'"