docs: build each documented branch's javadoc with the JDK it needs

.github/workflows/docs-pages.yml

@@ -36,10 +36,12 @@ jobs:
         with:
           python-version: '3.13'
 
-      - name: Set up JDK 11
+      - name: Set up JDK 8 and 11
         uses: actions/setup-java@be666c2fcd27ec809703dec50e508c2fdc7f6654 # v5.2.0
         with:
-          java-version: '11'
+          java-version: |
+            8
+            11
           distribution: 'temurin'
 
       - name: Install uv
@@ -53,11 +55,6 @@ jobs:
 
       - name: Build docs
         run: make -C docs multiversion
-        env:
-          # Old release branches (e.g. scylla-4.15.0.x) have javadoc
-          # comments that only pass doclint on JDK 8.
-          # Don't fail their multiversion javadoc builds on JDK 11.
-          MAVEN_OPTS: -Dmaven.javadoc.failOnError=false
 
       - name: Deploy docs to GitHub Pages
         run: ./docs/_utils/deploy.sh

README-dev.md

@@ -15,6 +15,18 @@ Once you have installed the above software, you can build and preview the docume
 
 To generate the reference documentation of the driver, run the command `make javadoc`. This command generates the reference documentation using the Javadoc tool in the `_build/dirhtml/<VERSION>/api` directory.
 
+## Multiversion build
+
+`make -C docs multiversion` builds the documentation site and javadoc for every branch in `BRANCHES` (`docs/source/conf.py`).
+
+`docs/_utils/javadoc-multiversion.sh` selects the JDK per branch: branches up to `scylla-4.19.0.x` need JDK 8, newer ones JDK 11.
+
+To add a new documented version:
+
+1. Add the branch to `BRANCHES` in `docs/source/conf.py`, and update `LATEST_VERSION` if it is the new latest. New branches build with JDK 11 by default.
+2. Only if the branch needs a different JDK, map it in `docs/_utils/javadoc-multiversion.sh`.
+3. Only if that JDK is not installed by the workflow yet, add it to the `setup-java` step in `.github/workflows/docs-pages.yml`.
+
 ## Using the Makefile
 
 Most day-to-day tasks are wrapped in the top-level `Makefile` so you do not have to remember long Maven invocations. Common targets include:

docs/_utils/javadoc-multiversion.sh

@@ -0,0 +1,37 @@
+#!/bin/bash
+#
+# Runs each documented version's javadoc.sh with the JDK that version needs.
+
+case "${SPHINX_MULTIVERSION_NAME:-}" in
+  scylla-4.7.2.x | \
+  scylla-4.10.0.x | \
+  scylla-4.11.1.x | \
+  scylla-4.12.0.x | \
+  scylla-4.13.0.x | \
+  scylla-4.14.1.x | \
+  scylla-4.15.0.x | \
+  scylla-4.17.0.x | \
+  scylla-4.18.1.x | \
+  scylla-4.19.0.x)
+    JDK_VERSION=8
+    ;;
+  *)
+    JDK_VERSION=11
+    ;;
+esac
+
+JDK_HOME_VAR="JAVA_HOME_${JDK_VERSION}_X64"
+SELECTED_JDK="${!JDK_HOME_VAR:-}"
+
+if [[ -n "$SELECTED_JDK" ]]; then
+    echo "Building javadoc for '${SPHINX_MULTIVERSION_NAME:-?}' with JDK ${JDK_VERSION} (${SELECTED_JDK})"
+    export JAVA_HOME="$SELECTED_JDK"
+    export PATH="$JAVA_HOME/bin:$PATH"
+elif [[ -n "${GITHUB_ACTIONS:-}" ]]; then
+    echo "${JDK_HOME_VAR} is not set: add JDK ${JDK_VERSION} to the setup-java step in docs-pages.yml" >&2
+    exit 1
+else
+    echo "Building javadoc for '${SPHINX_MULTIVERSION_NAME:-?}' with the default JDK (${JDK_HOME_VAR} is not set)"
+fi
+
+exec ./docs/_utils/javadoc.sh

docs/_utils/multiversion.sh

@@ -1,5 +1,5 @@
-#! /bin/bash	
+#! /bin/bash
 
 cd .. && 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 "$(pwd)/docs/_utils/javadoc-multiversion.sh"