[docs] Migrate reference documentation to Antora (#3806)

To build the documentation, JDK17+ is required. The documentation can be built as a separate step from the regular build that uses JDK8 to kick off Gradle. `./gradlew antora` task generates the documentation in `./docs/build/site` `./gradlew docs` packages documentation into a `docs.zip`
reactor · May 17, 2024 · 0c87bbd · 0c87bbd
1 parent 7cf5841
commit 0c87bbd
Show file tree

Hide file tree

Showing 88 changed files with 2,462 additions and 4,446 deletions.
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -7,6 +7,11 @@ on:
       - main
       - 3.6.x
 permissions: read-all
+
+env:
+  DOCS_ZIP: docs-zip
+  DOCS_ZIP_PATH: docs/build/distributions
+
 jobs:
   # General job notes: we DON'T want to cancel any previous runs, especially in the case of a "back to snapshots" build right after a release push
   # We specify the ubuntu version to minimize the chances we have to deal with a migration during a release
@@ -63,11 +68,41 @@ jobs:
       uses: gradle/actions/setup-gradle@db19848a5fa7950289d3668fb053140cf3028d43 # tag=v3
       with:
         arguments: ${{ matrix.test-type.arguments }}
+
+  # Build the docs-zip antora doc for the current branch, and upload generated docs-zip to workflow run.
+  # JDK21 is used because the antora plugin requires a JDK17 compatible version.
+  # Each deploy job can then download the docs-zip to ./docs/build/distributions/ in order to let it be included in published artifacts.
+  # (see gradle/setup.gradle publications which includes docs zip file, if found from docs/build/distributions directory)
+  build-docs-zip:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4
+      - name: Set up Ruby for asciidoctor-pdf
+        uses: ruby/setup-ruby@cacc9f1c0b3f4eb8a16a6bb0ed10897b43b9de49 # v1
+        with:
+          ruby-version: 3.3.0
+      - name: Install asciidoctor-pdf / rouge
+        run: gem install asciidoctor-pdf rouge
+      - name: Setup java 21 for antora
+        uses: actions/setup-java@99b8673ff64fbf99d8d325f52d9a5bdedb8483e9 # v4
+        with:
+          distribution: 'temurin'
+          java-version: '21'
+      - name: Build antora docs zip distribution for the current branch
+        run: ./gradlew docs
+      - name: Upload docs/build to current workflow run
+        uses: actions/upload-artifact@65462800fd760344b1a7b4382951275a0abb4808 # v4
+        with:
+          name: ${{ env.DOCS_ZIP }}
+          path: ${{ env.DOCS_ZIP_PATH }}
+          retention-days: 1
+          if-no-files-found: error
+
   #deploy the snapshot artifacts to Artifactory
   deploySnapshot:
     name: deploySnapshot
     runs-on: ubuntu-20.04
-    needs: prepare
+    needs: [prepare, build-docs-zip]
     if: needs.prepare.outputs.versionType == 'SNAPSHOT'
     environment: snapshots
     steps:
@@ -94,6 +129,11 @@ jobs:
       with:
         distribution: 'temurin'
         java-version: 8
+    - name: Download antora docs-zip
+      uses: actions/download-artifact@65a9edc5881444af0b9093a5e628f2fe47ea3b2e # v4
+      with:
+        name: ${{ env.DOCS_ZIP }}
+        path: ${{ env.DOCS_ZIP_PATH }}
     - name: deploy
       env:
         ORG_GRADLE_PROJECT_artifactory_publish_username: ${{secrets.ARTIFACTORY_SNAPSHOT_USERNAME}}
@@ -105,7 +145,7 @@ jobs:
   deployMilestone:
     name: deployMilestone
     runs-on: ubuntu-20.04
-    needs: prepare
+    needs: [prepare, build-docs-zip]
     if: needs.prepare.outputs.versionType == 'MILESTONE'
     environment: releases
     steps:
@@ -132,6 +172,11 @@ jobs:
       with:
         distribution: 'temurin'
         java-version: 8
+    - name: Download antora docs-zip
+      uses: actions/download-artifact@65a9edc5881444af0b9093a5e628f2fe47ea3b2e # v4
+      with:
+        name: ${{ env.DOCS_ZIP }}
+        path: ${{ env.DOCS_ZIP_PATH }}
     - name: deploy
       env:
         ORG_GRADLE_PROJECT_artifactory_publish_username: ${{secrets.ARTIFACTORY_USERNAME}}
@@ -145,7 +190,7 @@ jobs:
   deployRelease:
     name: deployRelease
     runs-on: ubuntu-20.04
-    needs: prepare
+    needs: [prepare, build-docs-zip]
     if: needs.prepare.outputs.versionType == 'RELEASE'
     environment: releases
     steps:
@@ -172,6 +217,11 @@ jobs:
       with:
         distribution: 'temurin'
         java-version: 8
+    - name: Download antora docs/build
+      uses: actions/download-artifact@65a9edc5881444af0b9093a5e628f2fe47ea3b2e # v4
+      with:
+        name: ${{ env.DOCS_ZIP }}
+        path: ${{ env.DOCS_ZIP_PATH }}
     - name: deploy
       env:
         ORG_GRADLE_PROJECT_artifactory_publish_username: ${{secrets.ARTIFACTORY_USERNAME}}
@@ -213,5 +263,23 @@ jobs:
           git tag -m "Release version ${{ needs.prepare.outputs.fullVersion }}" v${{ needs.prepare.outputs.fullVersion }} ${{ github.sha }}
           git push --tags
 
+  cleanup:
+    name: Cleanup docs-zip artifact
+    needs: [ deploySnapshot, tagRelease, tagMilestone ]
+    if: always() # cleanup always run after all needed jobs, regardless of whether they were successful
+    runs-on: ubuntu-20.04
+    permissions:
+      actions: write
+    steps:
+      - name: delete antora docs-zip artifact
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |-
+          ARTIFACTS_URL="/repos/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}/artifacts"
+          ARTIFACT_ID=$(gh api -H 'Accept: application/vnd.github+json' -H 'X-GitHub-Api-Version: 2022-11-28' $ARTIFACTS_URL | jq -r '.artifacts[] | select(.name == "'$DOCS_ZIP'") | .id // ""')
+          if [ -n "$ARTIFACT_ID" ]; then
+            gh api --method DELETE -H 'Accept: application/vnd.github+json' -H 'X-GitHub-Api-Version: 2022-11-28' /repos/${{github.repository}}/actions/artifacts/$ARTIFACT_ID}
+          fi
+
 # For Gradle configuration of signing, see https://docs.gradle.org/current/userguide/signing_plugin.html#sec:in-memory-keys
 # publishMavenJavaPublicationToSonatypeRepository only sends to a staging repository
diff --git a/README.md b/README.md
@@ -89,6 +89,18 @@ When the installations succeed, try to refresh the project and see that it build
 The manual Operation-system specific JDK installation
 is well explained in the [official docs](https://docs.oracle.com/en/java/javase/20/install/overview-jdk-installation.html)
 
+### Building the doc
+
+The current active shell JDK version must be compatible with JDK17 or higher for Antora to build successfully.
+So, just ensure that you have installed JDK 21, as described above and make it as the current one. 
+
+Then you can build the antora documentation like this:
+```shell
+./gradlew docs
+```
+
+The documentation is generated in `docs/build/site/index.html` and in `docs/build/distributions/reactor-core-<version-docs.zip` 
+
 ## Getting Started
 
 New to Reactive Programming or bored of reading already ? Try the [Introduction to Reactor Core hands-on](https://github.com/reactor/lite-rx-api-hands-on) !

diff --git a/build.gradle b/build.gradle
@@ -28,8 +28,6 @@ buildscript {
 plugins {
 	alias(libs.plugins.artifactory)
 	alias(libs.plugins.shadow)
-	alias(libs.plugins.asciidoctor.convert) apply false
-	alias(libs.plugins.asciidoctor.pdf) apply false
 	alias(libs.plugins.japicmp)
 	alias(libs.plugins.download)
 	// note: build scan plugin now must be applied in settings.gradle
@@ -42,7 +40,6 @@ plugins {
 }
 
 apply plugin: "io.reactor.gradle.detect-ci"
-apply from: "gradle/asciidoc.gradle" // asciidoc (which is generated from root dir)
 apply from: "gradle/releaser.gradle"
 apply from: "gradle/dependencies.gradle"
 apply from: "gradle/toolchains.gradle"
@@ -89,7 +86,9 @@ ext {
 }
 
 nohttp {
-	source.exclude "docs/asciidoc/highlight/**"
+	source.exclude "docs/modules/ROOT/assets/highlight/**"
+	source.exclude "docs/.gradle/**"
+	source.exclude "docs/build/**"
 	source.exclude "**/build/reports/tests/**/*.html"
 	allowlistFile = project.file('codequality/nohttp/allowlist.lines')
 }
@@ -199,9 +198,24 @@ configure(subprojects) { p ->
 			}
 		}
 	}
-}
 
-assemble.dependsOn docsZip
+	if (!JavaVersion.current().isCompatibleWith(JavaVersion.VERSION_17)) {
+		// If the JDK version is less than 17, the 'docs' subproject is not loaded, and therefore, the 'antora' or 'docs' tasks are unavailable.
+		// Display a friendly error message indicating that JDK 17 or higher is required
+
+		task antora {
+			doLast {
+				throw new GradleException("antora task requires JDK 17 or higher.")
+			}
+		}
+
+		task docs {
+			doLast {
+				throw new GradleException("docs task requires JDK 17 or higher")
+			}
+		}
+	}
+}
 
 configure(subprojects) { p ->
 	// these apply once the above configure is done, but before project-specific build.gradle have applied

diff --git a/docs/antora-assembler.yml b/docs/antora-assembler.yml
@@ -0,0 +1,9 @@
+root_level: 0
+build:
+    publish: false
+asciidoc:
+    build:
+        command: bundle exec asciidoctor-pdf -n -d book
+    attributes:
+        source-highlighter: rouge
+        pdf-theme: ./pdf-theme.yml
diff --git a/docs/antora-playbook.yml b/docs/antora-playbook.yml
@@ -0,0 +1,51 @@
+antora:
+  extensions:
+    - '@springio/antora-extensions/partial-build-extension'
+    # atlas-extension must be before latest-version-extension so latest versions are applied to imported versions
+    - '@antora/atlas-extension'
+    - require: '@springio/antora-extensions/latest-version-extension'
+    - require: '@springio/antora-extensions/inject-collector-cache-config-extension'
+    - '@antora/collector-extension'
+    - id: pdf-extension # pdf-extension is enabled from antora-docs.gradle
+      require: '@antora/pdf-extension'
+      enabled: false
+    - require: '@springio/antora-extensions/root-component-extension'
+      root_component_name: 'reactor'
+site:
+  title: Reactor Core Reference Guide
+  url: https://projectreactor.io/docs/core/release/reference
+content:
+  sources:
+    - url: ./..
+      branches: HEAD
+      start_path: docs
+      worktrees: true
+asciidoc:
+  extensions:
+    - '@asciidoctor/tabs'
+    - '@springio/asciidoctor-extensions'
+  attributes:
+    page-stackoverflow-url: https://stackoverflow.com/tags/project-reactor
+    page-pagination: ''
+    hide-uri-scheme: '@'
+    tabs-sync-option: '@'
+    chomp: 'all'
+    doctype: book
+    icons: font
+    toc2: true
+    sectnums: true
+    sectanchors: true
+    source-highlighter: highlightjs
+    highlightjsdir: modules/ROOT/assets/highlight
+    highlightjs-theme: railscasts
+  sourcemap: true
+urls:
+  latest_version_segment: ''
+runtime:
+  log:
+    failure_level: warn
+    format: pretty
+ui:
+  bundle:
+    url: https://github.com/reactor/antora-ui-projectreactor/releases/download/latest/ui-bundle.zip
+    snapshot: true
diff --git a/docs/antora.yml b/docs/antora.yml
@@ -0,0 +1,24 @@
+name: reactor
+version: true
+title: Reactor 3 Reference Guide
+start_page: aboutDoc.adoc
+nav:
+  - modules/ROOT/nav.adoc
+ext:
+  collector:
+    run:
+      command: gradlew -q "-Dorg.gradle.jvmargs=-Xmx3g -XX:+HeapDumpOnOutOfMemoryError" :docs:generateAntoraResources
+      local: true
+    scan:
+      dir: ./build/generated-antora-resources
+
+asciidoc:
+  attributes:
+    attribute-missing: 'warn'
+    chomp: 'all'
+    source-language: java
+    reactor-github-repo: 'https://github.com/reactor/reactor-core/tree/main'
+    javadoc: 'https://projectreactor.io/docs/core/{project-version}/api'
+    author:
+      - Stephane Maldini
+      - Simon Baslé