From b4d521e53df26da3d604cdcd71a7b4d89927f3f3 Mon Sep 17 00:00:00 2001
From: Mikita Hradovich <mikita.hradovich@scylladb.com>
Date: Tue, 22 Sep 2026 12:05:07 +0200
Subject: [PATCH] ci: read javadoc output from target/reports on scylla-3.x

maven-javadoc-plugin moved the javadoc goal's output from
target/site/apidocs to target/reports/apidocs in 3.11, and this branch
pins 3.11.3. The script still copies from target/site, so the glob never
matches, mv fails, and api/ publishes empty. The frozen scylla-3.*.x
branches pin 2.10.4, which is why scylla-3.x has gone unnoticed: it is
not a published docs version yet.

Resolve from either location, clear both first so the fallback is
unambiguous, and require a real non-empty index.html. Build only
driver-core: with set -e in force, a javadoc failure in another module
would otherwise cost the whole api/.

Fixes #1123
Refs: #1080, #1118

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 docs/_utils/javadoc.sh | 51 ++++++++++++++++++++++++++++++++++++------
 1 file changed, 44 insertions(+), 7 deletions(-)

diff --git a/docs/_utils/javadoc.sh b/docs/_utils/javadoc.sh
index 5fadf3954d4..ab3bfeb263c 100755
--- a/docs/_utils/javadoc.sh
+++ b/docs/_utils/javadoc.sh
@@ -1,17 +1,54 @@
 #!/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
-mkdir -p "$OUTPUT_DIR"
-mv -f driver-core/target/site/apidocs/* $OUTPUT_DIR
+# Generate javadoc. driver-core is the only module the published api/ contains, and restricting
+# the reactor keeps a javadoc failure in driver-mapping or driver-extras from costing it;
+# javadoc:javadoc is a standalone goal so it resolves from the repository, not the reactor.
+JAVADOC_MODULE=driver-core
+# The api/ package the module contributes. The publish only checks that api/index.html is
+# non-empty, so a run that generated nothing else would be invisible downstream.
+JAVADOC_API_PACKAGE=com/datastax/driver/core
+
+# Nothing here runs clean, so drop the previous run's output: it is indistinguishable from this
+# run's, and an empty run would otherwise republish it as current.
+rm -rf "$JAVADOC_MODULE/target/reports/apidocs" "$JAVADOC_MODULE/target/site/apidocs"
+
+mvn javadoc:javadoc -pl "$JAVADOC_MODULE" -T 1C
+
+# maven-javadoc-plugin writes to target/reports from 3.11 on, and to target/site before it.
+apidocs_dir() {
+    local module="$1" package="$2" candidate
+    for candidate in "$module/target/reports/apidocs" "$module/target/site/apidocs"; do
+        if [[ -f "$candidate/index.html" && -s "$candidate/index.html" && -d "$candidate/$package" ]]; then
+            printf '%s' "$candidate"
+            return 0
+        fi
+    done
+    echo "No javadoc output holding $package for $module" >&2
+    return 1
+}
+
+# Resolve before touching $OUTPUT_DIR: the default branch's javadoc-multiversion.sh downgrades our
+# exit code to a warning, so whatever api/ holds by then is what gets deployed.
+source_dir="$(apidocs_dir "$JAVADOC_MODULE" "$JAVADOC_API_PACKAGE")" || exit 1
+
+# Assemble alongside and swap in, so a failed copy cannot leave a partial api/, and clean the
+# staging tree up on any exit so a failure cannot deploy it next to the real one.
+staging_dir="$OUTPUT_DIR.new"
+trap 'rm -rf "$staging_dir"' EXIT
+rm -rf "$staging_dir"
+mkdir -p "$staging_dir"
+# Copy rather than move, so the source survives a second run.
+cp -a "$source_dir/." "$staging_dir"
+rm -rf "$OUTPUT_DIR"
+mv "$staging_dir" "$OUTPUT_DIR"