Antora

.github/workflows/deploy-docs.yml

@@ -0,0 +1,33 @@
+name: Deploy Docs
+on:
+  push:
+    branches-ignore: [ gh-pages ]
+    tags: '**'
+  repository_dispatch:
+    types: request-build-reference # legacy
+  #schedule:
+  #- cron: '0 10 * * *' # Once per day at 10am UTC
+  workflow_dispatch:
+permissions:
+  actions: write
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    # FIXME: enable when pushed to spring-projects
+    # if: github.repository_owner == 'spring-projects'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          ref: docs-build
+          fetch-depth: 1
+      - name: Dispatch (partial build)
+        if: github.ref_type == 'branch'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD) -f build-refname=${{ github.ref_name }}
+      - name: Dispatch (full build)
+        if: github.ref_type == 'tag'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD)

build.gradle

@@ -24,8 +24,6 @@ plugins {
 	id 'io.spring.nohttp' version '0.0.11'
 	id 'io.spring.dependency-management' version '1.0.10.RELEASE' apply false
 	id 'com.jfrog.artifactory' version '4.33.1' apply false
-	id 'org.asciidoctor.jvm.pdf' version '3.3.2'
-	id 'org.asciidoctor.jvm.convert' version '3.3.2'
 }
 
 apply plugin: 'io.spring.nohttp'
@@ -45,7 +43,6 @@ ext {
 	linkScmUrl = 'https://github.com/spring-projects/spring-kafka'
 	linkScmConnection = 'https://github.com/spring-projects/spring-kafka.git'
 	linkScmDevConnection = '[email protected]:spring-projects/spring-kafka.git'
-	springAsciidoctorBackendsVersion = '0.0.7'
 
 	javadocLinks = [
 		'https://docs.oracle.com/en/java/javase/17/docs/api/',
@@ -54,8 +51,8 @@ ext {
 
 
 	if (gitPresent) {
-		modifiedFiles =
-			files(grgit.status().unstaged.modified).filter{ f -> f.name.endsWith('.java') || f.name.endsWith('.kt') }
+		modifiedFiles =  providers.provider {
+			files(grgit.status().unstaged.modified).filter{ f -> f.name.endsWith('.java') || f.name.endsWith('.kt') } }
 	}
 
 	assertjVersion = '3.24.2'
@@ -249,7 +246,7 @@ configure(javaProjects) { subproject ->
 	task updateCopyrights {
 		onlyIf { !isCI }
 		if (gitPresent) {
-			inputs.files(modifiedFiles.filter { f -> f.path.contains(subproject.name) })
+			inputs.files(modifiedFiles.map(files -> files.filter { f -> f.path.contains(subproject.name) }))
 		}
 		outputs.dir('build/classes')
 
@@ -454,22 +451,13 @@ sonarqube {
 }
 
 configurations {
-	asciidoctorExtensions
 	micrometerDocs
 }
 
 dependencies {
-	asciidoctorExtensions "io.spring.asciidoctor.backends:spring-asciidoctor-backends:${springAsciidoctorBackendsVersion}"
 	micrometerDocs "io.micrometer:micrometer-docs-generator:$micrometerDocsVersion"
 }
 
-task prepareAsciidocBuild(type: Sync) {
-	dependsOn configurations.asciidoctorExtensions
-	duplicatesStrategy = DuplicatesStrategy.EXCLUDE
-	from 'spring-kafka-docs/src/main/asciidoc/','spring-kafka-docs/src/main/java','spring-kafka-docs/src/main/kotlin'
-	into "$buildDir/asciidoc"
-}
-
 def observationInputDir = file('spring-kafka/src/main/java/org/springframework/kafka/support/micrometer').absolutePath
 def generatedDocsDir = file("$buildDir/docs/generated").absolutePath
 
@@ -490,78 +478,6 @@ task filterMetricsDocsContent(type: Copy) {
 	filter { line -> line.replaceAll('org.springframework.kafka.support.micrometer.', '').replaceAll('^Fully qualified n', 'N') }
 }
 
-asciidoctorPdf {
-	dependsOn prepareAsciidocBuild, filterMetricsDocsContent
-	baseDirFollowsSourceFile()
-	configurations 'asciidoctorExtensions'
-
-	asciidoctorj {
-		sourceDir "$buildDir/asciidoc"
-		inputs.dir(sourceDir).withPathSensitivity(PathSensitivity.RELATIVE)
-		sources {
-			include 'index.adoc'
-		}
-		options doctype: 'book'
-		attributes 'icons': 'font',
-		'sectanchors': '',
-		'sectnums': '',
-		'toc': '',
-		'source-highlighter' : 'coderay',
-		revnumber: project.version,
-		'project-version': project.version
-	}
-}
-
-asciidoctorj {
-	version = '2.4.1'
-	// fatalWarnings ".*"
-	options doctype: 'book', eruby: 'erubis'
-	attributes([
-			icons: 'font',
-			idprefix: '',
-			idseparator: '-',
-			docinfo: 'shared',
-			revnumber: project.version,
-			sectanchors: '',
-			sectnums: '',
-			'source-highlighter': 'highlight.js',
-			highlightjsdir: 'js/highlight',
-			'highlightjs-theme': 'googlecode',
-			stylesdir: 'css/',
-			stylesheet: 'stylesheet.css',
-			'spring-version': project.version,
-			'project-version': project.version,
-			'java-examples': 'org/springframework/kafka/jdocs',
-			'kotlin-examples': 'org/springframework/kafka/kdocs'
-	])
-}
-
-asciidoctor {
-	dependsOn asciidoctorPdf
-	baseDirFollowsSourceFile()
-	configurations 'asciidoctorExtensions'
-	sourceDir = file("$buildDir/asciidoc")
-	outputOptions {
-		backends "spring-html"
-	}
-	sources {
-		include '*.adoc'
-	}
-	resources {
-		from(sourceDir) {
-			include 'images/*', 'css/**', 'js/**'
-		}
-	}
-
-}
-
-task reference(dependsOn: asciidoctor) {
-	group = 'Documentation'
-	description = 'Generate the reference documentation'
-}
-
-reference.onlyIf { "$System.env.NO_REFERENCE_TASK" != 'true' || project.hasProperty('ignoreEnvToStopReference') }
-
 task api(type: Javadoc) {
 	group = 'Documentation'
 	description = 'Generates aggregated Javadoc API documentation.'
@@ -588,7 +504,7 @@ task api(type: Javadoc) {
 	destinationDir = new File(buildDir, 'api')
 }
 
-task docsZip(type: Zip, dependsOn: [reference]) {
+task docsZip(type: Zip, dependsOn: ['antora']) {
 	group = 'Distribution'
 	archiveClassifier = 'docs'
 	description = "Builds -${archiveClassifier} archive containing api and reference " +
@@ -602,14 +518,8 @@ task docsZip(type: Zip, dependsOn: [reference]) {
 		into 'api'
 	}
 
-	from ('build/docs/asciidoc') {
-		into 'reference/html'
-	}
-
-	from ('build/docs/asciidocPdf') {
-		include 'index.pdf'
-		rename 'index.pdf', 'spring-kafka-reference.pdf'
-		into 'reference/pdf'
+	from ('build/site') {
+		into 'reference/'
 	}
 }
 

gradle/docs.gradle

@@ -0,0 +1,34 @@
+
+
+antora {
+	version = '3.2.0-alpha.2'
+	playbook = file('src/main/antora/antora-playbook.yml')
+	options = ['to-dir' : project.layout.buildDirectory.dir('site').get().toString(), clean: true, fetch: !project.gradle.startParameter.offline, stacktrace: true]
+	dependencies = [
+			'@antora/atlas-extension': '1.0.0-alpha.1',
+			'@antora/collector-extension': '1.0.0-alpha.3',
+			'@asciidoctor/tabs': '1.0.0-beta.3',
+			'@springio/antora-extensions': '1.4.2',
+			'@springio/asciidoctor-extensions': '1.0.0-alpha.8',
+	]
+}
+
+tasks.named("generateAntoraYml") {
+	asciidocAttributes = project.provider( {
+		return ['project-version' : project.version,
+				'revnumber': project.version,
+				'spring-version': project.version,
+		]
+	} )
+	baseAntoraYmlFile = file('src/main/antora/antora.yml')
+}
+
+tasks.create(name: 'createAntoraPartials', type: Sync) {
+	from { project.rootProject.tasks.filterMetricsDocsContent.outputs }
+	into layout.buildDirectory.dir('generated-antora-resources/modules/ROOT/partials')
+}
+
+tasks.create('generateAntoraResources') {
+	dependsOn 'createAntoraPartials'
+	dependsOn 'generateAntoraYml'
+}

spring-kafka-docs/build.gradle

@@ -1,3 +1,10 @@
+plugins {
+    id 'org.antora' version '1.0.0'
+    id 'io.spring.antora.generate-antora-yml' version '0.0.1'
+}
+
+apply from: "${rootDir}/gradle/docs.gradle"
+
 jar {
     enabled = false
 }

spring-kafka-docs/src/main/antora/antora-playbook.yml

@@ -0,0 +1,44 @@
+antora:
+  extensions:
+    - '@springio/antora-extensions/partial-build-extension'
+    - require: '@springio/antora-extensions/latest-version-extension'
+    - require: '@springio/antora-extensions/inject-collector-cache-config-extension'
+    - '@antora/collector-extension'
+    - '@antora/atlas-extension'
+    - require: '@springio/antora-extensions/root-component-extension'
+      root_component_name: 'kafka'
+      # FIXME: Run antora once using this extension to migrate to the Asciidoc Tabs syntax
+      # and then remove this extension
+    - require: '@springio/antora-extensions/tabs-migration-extension'
+      unwrap_example_block: always
+      save_result: true
+site:
+  title: Spring Kafka
+  url: https://docs.spring.io/spring-kafka/reference/
+content:
+  sources:
+    - url: ./../../../../
+      branches: HEAD
+      # See https://docs.antora.org/antora/latest/playbook/content-source-start-path/#start-path-key
+      start_path: spring-kafka-docs/src/main/antora
+      worktrees: true
+asciidoc:
+  attributes:
+    page-stackoverflow-url: https://stackoverflow.com/tags/spring-kafka
+    page-pagination: ''
+    hide-uri-scheme: '@'
+    tabs-sync-option: '@'
+    chomp: 'all'
+  extensions:
+    - '@asciidoctor/tabs'
+    - '@springio/asciidoctor-extensions'
+  sourcemap: true
+urls:
+  latest_version_segment: ''
+runtime:
+  log:
+    failure_level: warn
+    format: pretty
+ui:
+  bundle:
+    url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.3.5/ui-bundle.zip

spring-kafka-docs/src/main/antora/antora.yml

@@ -0,0 +1,27 @@
+name: kafka
+version: true
+title: Spring Kafka
+nav:
+  - modules/ROOT/nav.adoc
+ext:
+  collector:
+    run:
+      # FIXME Change "command" to the command that generates your antora.yml and other antora resources
+      # See https://gitlab.com/antora/antora-collector-extension/-/blob/main/docs/modules/ROOT/pages/configuration-keys.adoc?ref_type=heads#collector-reference
+      # HINT: Maven is typically something like:
+      # ./mvnw validate process-resources -am -Pantora-process-resources
+      command: gradlew -q "-Dorg.gradle.jvmargs=-Xmx3g -XX:+HeapDumpOnOutOfMemoryError" :spring-kafka-docs:generateAntoraResources
+      local: true
+    scan:
+      # FIXME Change "dir" to the location that generated files are at
+      # See https://gitlab.com/antora/antora-collector-extension/-/blob/main/docs/modules/ROOT/pages/configuration-keys.adoc?ref_type=heads#collector-reference
+      # HINT: Maven is typically something like:
+      # target/classes/antora-resources/
+      dir: spring-kafka-docs/build/generated-antora-resources
+
+asciidoc:
+  attributes:
+    attribute-missing: 'warn'
+    chomp: 'all'
+    java-examples: example$java-examples/org/springframework/kafka/jdocs
+    kotlin-examples: example$kotlin-examples/org/springframework/kafka/kdocs

spring-kafka-docs/src/main/antora/modules/ROOT/examples/java-examples

@@ -0,0 +1 @@
+../../../../java/

spring-kafka-docs/src/main/antora/modules/ROOT/examples/kotlin-examples

@@ -0,0 +1 @@
+../../../../kotlin/

spring-kafka-docs/src/main/antora/modules/ROOT/nav.adoc

@@ -0,0 +1,68 @@
+* xref:index.adoc[]
+* xref:whats-new.adoc[]
+* xref:introduction.adoc[]
+** xref:quick-tour.adoc[]
+* xref:reference.adoc[]
+** xref:kafka.adoc[]
+*** xref:kafka/connecting.adoc[]
+*** xref:kafka/configuring-topics.adoc[]
+*** xref:kafka/sending-messages.adoc[]
+*** xref:kafka/receiving-messages.adoc[]
+**** xref:kafka/receiving-messages/message-listeners.adoc[]
+**** xref:kafka/receiving-messages/message-listener-container.adoc[]
+**** xref:kafka/receiving-messages/ooo-commits.adoc[]
+**** xref:kafka/receiving-messages/listener-annotation.adoc[]
+**** xref:kafka/receiving-messages/listener-group-id.adoc[]
+**** xref:kafka/receiving-messages/container-thread-naming.adoc[]
+**** xref:kafka/receiving-messages/listener-meta.adoc[]
+**** xref:kafka/receiving-messages/class-level-kafkalistener.adoc[]
+**** xref:kafka/receiving-messages/kafkalistener-attrs.adoc[]
+**** xref:kafka/receiving-messages/kafkalistener-lifecycle.adoc[]
+**** xref:kafka/receiving-messages/validation.adoc[]
+**** xref:kafka/receiving-messages/rebalance-listeners.adoc[]
+**** xref:kafka/receiving-messages/annotation-send-to.adoc[]
+**** xref:kafka/receiving-messages/filtering.adoc[]
+**** xref:kafka/receiving-messages/retrying-deliveries.adoc[]
+**** xref:kafka/receiving-messages/sequencing.adoc[]
+**** xref:kafka/receiving-messages/template-receive.adoc[]
+*** xref:kafka/container-props.adoc[]
+*** xref:kafka/dynamic-containers.adoc[]
+*** xref:kafka/events.adoc[]
+*** xref:kafka/topic/partition-initial-offset.adoc[]
+*** xref:kafka/seek.adoc[]
+*** xref:kafka/container-factory.adoc[]
+*** xref:kafka/thread-safety.adoc[]
+*** xref:kafka/micrometer.adoc[]
+*** xref:kafka/transactions.adoc[]
+*** xref:kafka/exactly-once.adoc[]
+*** xref:kafka/interceptors.adoc[]
+*** xref:kafka/producer-interceptor-managed-in-spring.adoc[]
+*** xref:kafka/pause-resume.adoc[]
+*** xref:kafka/pause-resume-partitions.adoc[]
+*** xref:kafka/serdes.adoc[]
+*** xref:kafka/headers.adoc[]
+*** xref:kafka/tombstones.adoc[]
+*** xref:kafka/annotation-error-handling.adoc[]
+*** xref:kafka/kerberos.adoc[]
+** xref:retrytopic.adoc[]
+*** xref:retrytopic/how-the-pattern-works.adoc[]
+*** xref:retrytopic/back-off-delay-precision.adoc[]
+*** xref:retrytopic/retry-config.adoc[]
+*** xref:retrytopic/programmatic-construction.adoc[]
+*** xref:retrytopic/features.adoc[]
+*** xref:retrytopic/retry-topic-combine-blocking.adoc[]
+*** xref:retrytopic/accessing-delivery-attempts.adoc[]
+*** xref:retrytopic/topic-naming.adoc[]
+*** xref:retrytopic/multi-retry.adoc[]
+*** xref:retrytopic/dlt-strategies.adoc[]
+*** xref:retrytopic/retry-topic-lcf.adoc[]
+*** xref:retrytopic/access-topic-info-runtime.adoc[]
+*** xref:retrytopic/change-kboe-logging-level.adoc[]
+** xref:streams.adoc[]
+** xref:testing.adoc[]
+* xref:tips.adoc[]
+* xref:other-resources.adoc[]
+* xref:appendix/override-boot-dependencies.adoc[]
+* xref:appendix/micrometer.adoc[]
+* xref:appendix/native-images.adoc[]
+* xref:appendix/change-history.adoc[]