Migrate reference documentation to Antora

.github/workflows/publish.yml

@@ -6,6 +6,9 @@ on:
       - 1.3.x
       - 1.2.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
@@ -43,11 +46,39 @@ jobs:
             */build/reports/tests/**/*.*
           retention-days: 3
 
+  # 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.
+  build-docs-zip:
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # 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: 3
+          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:
@@ -56,6 +87,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}}
@@ -67,7 +103,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:
@@ -76,6 +112,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}}
@@ -89,7 +130,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:
@@ -98,6 +139,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}}
@@ -139,5 +185,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() && (needs.deploySnapshot.result == 'success' || needs.tagRelease.result == 'success' || needs.tagMilestone.result == 'success')
+    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

build.gradle

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011-2023 VMware Inc. or its affiliates, All Rights Reserved.
+ * Copyright (c) 2011-2024 VMware Inc. or its affiliates, All Rights Reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -23,8 +23,6 @@ buildscript {
 
 plugins {
   id("jacoco-report-aggregation")
-  alias(libs.plugins.asciidoctor.convert) apply false
-  alias(libs.plugins.asciidoctor.pdf) apply false
   alias(libs.plugins.artifactory) apply false
   alias(libs.plugins.spotless)
 }
@@ -47,7 +45,7 @@ ext {
   //NOTE: all dependencies, including plugins, are defined in gradle/libs.versions.toml catalog
 }
 
-apply from: "${rootDir}/gradle/asciidoc.gradle"
+apply from: "${rootDir}/gradle/antoradoc.gradle"
 apply from: "${rootDir}/gradle/releaser.gradle"
 
 configurations.all {
@@ -112,6 +110,10 @@ configure(allprojects) { project ->
   [compileJava, compileTestJava]*.options*.compilerArgs = ['-Xlint:all,-options']
 
   java {
+    toolchain {
+      languageVersion = JavaLanguageVersion.of(name == "docs" ? 17 : 8)
+    }
+
     registerFeature('optional') {
         usingSourceSet(sourceSets.main)
     }
@@ -139,8 +141,8 @@ configure(allprojects) { project ->
     dependsOn test
     sourceSets sourceSets.main
     reports {
-      html.enabled = true
-      xml.enabled = true
+      html.required = true
+      xml.required = true
     }
   }
   jacocoTestReport.dependsOn test
@@ -169,6 +171,23 @@ configure(allprojects) { project ->
     testImplementation libs.awaitility
     testImplementation libs.assertj
   }
+
+  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(rootProject) {

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

docs/antora-playbook.yml

@@ -0,0 +1,52 @@
+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-kafka'
+site:
+  title: Reactor Kafka Reference Guide
+  url: https://projectreactor.io/docs/kafka/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/reactor-kafka
+    page-pagination: ''
+    hide-uri-scheme: '@'
+    tabs-sync-option: '@'
+    chomp: 'all'
+    doctype: book
+    icons: font
+    toc2: true
+    sectnums: true
+    sectanchors: true
+    numbered: 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

docs/antora.yml

@@ -0,0 +1,27 @@
+name: reactor-kafka
+version: true
+title: Reactor Kafka Reference Guide
+start_page: overview.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
+    github-repo: reactor/reactor-kafka
+    github-code: https://github.com/{github-repo}
+    javadoc: 'https://projectreactor.io/docs/kafka/{project-version}/api'
+    author:
+      - Rajini Sivaram
+      - Mark Pollack
+      - Oleh Dokuka
+      - Gary Russell

docs/build.gradle

@@ -0,0 +1,94 @@
+/*
+ * Copyright (c) 2024 VMware Inc. or its affiliates, All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+plugins {
+  alias(libs.plugins.antora)
+  alias(libs.plugins.antora.yml)
+}
+
+def isCommandAvailable(String command) {
+  def result = exec {
+    commandLine 'which', command
+    ignoreExitValue true
+    standardOutput = new ByteArrayOutputStream()
+    errorOutput = new ByteArrayOutputStream()
+  }
+  return result.exitValue == 0
+}
+
+antora {
+  version = libs.versions.antora.version
+  playbook = findProperty('antora.playbook') ?: "antora-playbook.yml"
+  options = ['--clean', '--stacktrace']
+
+  def version = project.version
+  def forcePdf = project.hasProperty('forcePdf')
+
+  if (!version.endsWith("-SNAPSHOT") || forcePdf) {
+    if (isCommandAvailable('asciidoctor-pdf')) {
+      logger.log(LogLevel.DEBUG, "enabling antora pdf-extension")
+      options.add('--extension=pdf-extension')
+    } else {
+      throw new GradleException("PDF cannot be generated, asciidoctor-pdf not found from the PATH.")
+    }
+  }
+
+  environment = [
+    'ALGOLIA_API_KEY'   : 'd4bf9918bfc7d63ae68fbf92d69c2f49',
+    'ALGOLIA_APP_ID'    : '82SNR5M8HE',
+    'ALGOLIA_INDEX_NAME': 'projectreactor'
+  ]
+
+  dependencies = [
+    '@antora/atlas-extension'         : "${libs.versions.antora.atlas.extension.get()}",
+    '@antora/pdf-extension'           : "${libs.versions.antora.pdf.extension.get()}",
+    '@antora/collector-extension'     : "${libs.versions.antora.collector.extension.get()}",
+    '@asciidoctor/tabs'               : "${libs.versions.antora.tabs.extension.get()}",
+    '@springio/antora-extensions'     : "${libs.versions.antora.springio.antora.extension.get()}",
+    '@springio/asciidoctor-extensions': "${libs.versions.antora.asciidoctor.extension.get()}"
+  ]
+}
+
+jar {
+  enabled = false
+}
+
+javadoc {
+  enabled = false
+}
+
+tasks.withType(AbstractPublishToMaven).configureEach {
+  enabled = false
+}
+
+tasks.named("generateAntoraYml") {
+  asciidocAttributes = project.provider({ generateAttributes() })
+  baseAntoraYmlFile = file("antora.yml")
+}
+
+tasks.create('generateAntoraResources') {
+  dependsOn 'generateAntoraYml'
+}
+
+def generateAttributes() {
+  return ['is-snapshot-version': project.version.endsWith("-SNAPSHOT"),
+          'project-version'    : project.version
+  ]
+}
+
+description = "Reactor Kafka Antora Docs"
+
+// docsZip is added to reactor-kafka root project using gradle/antoradoc.gradle