From 9abbc937e96a6b63f21272667c08bdb1f6d36c05 Mon Sep 17 00:00:00 2001 From: Dmitry Kropachev Date: Wed, 27 May 2026 12:59:17 -0400 Subject: [PATCH] docs: build multiversion Javadocs 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. Keep docs multiversion execution on the upstream serial sphinx-multiversion path while selecting the right Java runtime before each version's checked-out Javadoc step. 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. --- .github/workflows/docs-pages.yml | 8 ++++++++ .github/workflows/docs-pr.yml | 11 +++++++++++ docs/_utils/javadoc.sh | 25 +++++++++++++++++++++---- docs/_utils/multiversion-javadoc.sh | 29 +++++++++++++++++++++++++++++ docs/_utils/multiversion.sh | 10 +++++++--- 5 files changed, 76 insertions(+), 7 deletions(-) create mode 100755 docs/_utils/multiversion-javadoc.sh diff --git a/.github/workflows/docs-pages.yml b/.github/workflows/docs-pages.yml index 7ec207fad09..f1632c299c6 100644 --- a/.github/workflows/docs-pages.yml +++ b/.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: diff --git a/.github/workflows/docs-pr.yml b/.github/workflows/docs-pr.yml index 744838e1dc3..99438a352a8 100644 --- a/.github/workflows/docs-pr.yml +++ b/.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 diff --git a/docs/_utils/javadoc.sh b/docs/_utils/javadoc.sh index 0c39996f68b..419ecfa112f 100755 --- a/docs/_utils/javadoc.sh +++ b/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" diff --git a/docs/_utils/multiversion-javadoc.sh b/docs/_utils/multiversion-javadoc.sh new file mode 100755 index 00000000000..cd7815193de --- /dev/null +++ b/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 diff --git a/docs/_utils/multiversion.sh b/docs/_utils/multiversion.sh index 78e0d58ff3e..abb296a36b1 100755 --- a/docs/_utils/multiversion.sh +++ b/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'"