docs: make multiversion build Java 11 compatible

Author: dkropachev

.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/**'

.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/**'
@@ -45,3 +47,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-javadoc.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+set -euo pipefail
+
+VERSION_NAME="${SPHINX_MULTIVERSION_NAME:-unknown}"
+
+echo "Building Javadocs for ${VERSION_NAME} with Java:"
+java -version
+
+make_legacy_checkout_java11_compatible() {
+    if [[ ! -f pom.xml ]] || ! grep -q "javac-with-errorprone" pom.xml; then
+        return
+    fi
+
+    echo "Adapting legacy ${VERSION_NAME} checkout for a Java 11 docs build"
+
+    perl -0pi -e 's/\n\s*<compilerId>javac-with-errorprone<\/compilerId>//g' pom.xml
+    perl -0pi -e 's/\n\s*<forceJavacCompilerUse>true<\/forceJavacCompilerUse>//g' pom.xml
+    perl -0pi -e 's/\n\s*<compilerArgs[^>]*>\s*<compilerArg>-Xep:FutureReturnValueIgnored:OFF<\/compilerArg>.*?<\/compilerArgs>//sg' pom.xml
+    perl -0pi -e 's/\n\s*<dependencies>\s*<dependency>\s*<groupId>org\.codehaus\.plexus<\/groupId>\s*<artifactId>plexus-compiler-javac-errorprone<\/artifactId>.*?<\/dependencies>//sg' pom.xml
+    perl -0pi -e 's/<failOnWarning>true<\/failOnWarning>/<failOnWarning>false<\/failOnWarning>/g' pom.xml
+}
+
+make_legacy_javadocs_java11_compatible() {
+    if [[ -f docs/_utils/javadoc.sh ]] && ! grep -q -- "-Dmaven.javadoc.skip=true" docs/_utils/javadoc.sh; then
+        perl -0pi -e 's/mvn install -DskipTests( -T 1C)?/mvn install -DskipTests -Dmaven.javadoc.skip=true$1/g' \
+            docs/_utils/javadoc.sh
+    fi
+
+    if [[ -f pom.xml ]] && grep -q "<name>leaks</name>" pom.xml; then
+        perl -0pi -e 's/<name>leaks<\/name>/<name>leaks-private-api<\/name>/g' pom.xml
+    fi
+
+    if [[ -f pom.xml ]]; then
+        perl -0pi -e 's/\n\s*<links>\s*<link>.*?<\/links>//sg' pom.xml
+    fi
+
+    if [[ -f core/src/main/java/com/datastax/oss/driver/api/core/CqlIdentifier.java ]]; then
+        perl -0pi -e 's/<table summary="examples">/<table>\n *   <caption>Examples<\/caption>/g' \
+            core/src/main/java/com/datastax/oss/driver/api/core/CqlIdentifier.java
+    fi
+}
+
+clean_javadoc_output() {
+    local output_dir="docs/_build/dirhtml/api"
+
+    if [[ -n "${SPHINX_MULTIVERSION_OUTPUTDIR:-}" ]]; then
+        output_dir="${SPHINX_MULTIVERSION_OUTPUTDIR}/api"
+    fi
+
+    rm -rf "$output_dir"
+}
+
+make_legacy_checkout_java11_compatible
+make_legacy_javadocs_java11_compatible
+clean_javadoc_output
+
+bash -e ./docs/_utils/javadoc.sh

docs/_utils/multiversion.sh

@@ -1,5 +1,8 @@
-#! /bin/bash	
+#! /bin/bash
+set -euo pipefail
 
-cd .. && sphinx-multiversion docs/source docs/_build/dirhtml \
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && 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 "$REPO_ROOT/docs/_utils/multiversion-javadoc.sh"