Switch the reference documentation to Antora

.github/workflows/deploy-docs.yml

@@ -0,0 +1,32 @@
+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
+    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)

.gitignore

@@ -50,3 +50,5 @@ atlassian-ide-plugin.xml
 
 # VS Code
 .vscode/
+
+cached-antora-playbook.yml

build.gradle

@@ -155,6 +155,7 @@ configure(rootProject) {
 
 	nohttp {
 		source.exclude "**/test-output/**"
+		source.exclude "**/.gradle/**"
 		allowlistFile = project.file("src/nohttp/allowlist.lines")
 		def rootPath = file(rootDir).toPath()
 		def projectDirs = allprojects.collect { it.projectDir } + "${rootDir}/buildSrc"

framework-docs/antora.yml

@@ -0,0 +1,32 @@
+name: framework
+version: true
+title: Spring Framework
+nav:
+  - modules/ROOT/nav.adoc
+ext:
+  collector:
+    run:
+      command: gradlew -q -PbuildSrc.skipTests=true "-Dorg.gradle.jvmargs=-Xmx3g -XX:+HeapDumpOnOutOfMemoryError" :framework-docs:generateAntoraResources
+      local: true
+    scan:
+      dir: ./build/generated-antora-resources
+
+asciidoc:
+  attributes:
+    attribute-missing: 'warn'
+    # FIXME: the copyright is not removed
+    # FIXME: The package is not renamed
+    chomp: 'all'
+    include-java: 'example$docs-src/main/java/org/springframework/docs'
+    spring-framework-main-code: 'https://github.com/spring-projects/spring-framework/tree/main'
+    docs-site: 'https://docs.spring.io'
+    docs-spring: "{docs-site}/spring-framework/docs/{spring-version}"
+    docs-spring-framework: '{docs-site}/spring-framework/docs/{spring-version}'
+    api-spring-framework: '{docs-spring-framework}/javadoc-api/org/springframework'
+    docs-graalvm: 'https://www.graalvm.org/22.3/reference-manual'
+    docs-spring-boot: '{docs-site}/spring-boot/docs/current/reference'
+    docs-spring-gemfire: '{docs-site}/spring-gemfire/docs/current/reference'
+    docs-spring-security: '{docs-site}/spring-security/reference'
+    gh-rsocket: 'https://github.com/rsocket'
+    gh-rsocket-extensions: '{gh-rsocket}/rsocket/blob/master/Extensions'
+    gh-rsocket-java: '{gh-rsocket}/rsocket-java{gh-rsocket}/rsocket-java'

framework-docs/framework-docs.gradle

@@ -1,22 +1,52 @@
+plugins {
+	id 'kotlin'
+	id 'io.spring.antora.generate-antora-yml' version '0.0.1'
+	id 'org.antora' version '1.0.0'
+}
+
 description = "Spring Framework Docs"
 
-apply plugin: 'kotlin'
-apply plugin: 'org.asciidoctor.jvm.convert'
-apply plugin: 'org.asciidoctor.jvm.pdf'
 apply from: "${rootDir}/gradle/publications.gradle"
 
 
-configurations {
-	asciidoctorExtensions
+antora {
+	version = '3.2.0-alpha.2'
+	playbook = 'cached-antora-playbook.yml'
+	playbookProvider {
+		repository = 'rwinch/spring-framework'
+		branch = 'docs-build'
+		path = 'lib/antora/templates/per-branch-antora-playbook.yml'
+		checkLocalBranch = true
+	}
+	options = ['--clean', '--stacktrace']
+	environment = [
+			'ALGOLIA_API_KEY': '82c7ead946afbac3cf98c32446154691',
+			'ALGOLIA_APP_ID': '244V8V9FGG',
+			'ALGOLIA_INDEX_NAME': 'framework-docs'
+	]
+	dependencies = [
+			'@antora/atlas-extension': '1.0.0-alpha.1',
+			'@antora/collector-extension': '1.0.0-alpha.3',
+			'@asciidoctor/tabs': '1.0.0-beta.3',
+			'@opendevise/antora-release-line-extension': '1.0.0-alpha.2',
+			'@springio/antora-extensions': '1.3.0',
+			'@springio/asciidoctor-extensions': '1.0.0-alpha.9'
+	]
 }
 
-dependencies {
-	api(project(":spring-context"))
-	api(project(":spring-web"))
-	api("jakarta.servlet:jakarta.servlet-api")
 
-	implementation(project(":spring-core-test"))
-	implementation("org.assertj:assertj-core")
+tasks.named("generateAntoraYml") {
+	asciidocAttributes = project.provider( {
+		return  ["spring-version": project.version ]
+	} )
+}
+
+tasks.create("generateAntoraResources") {
+	dependsOn 'generateAntoraYml'
+}
+
+tasks.named("check") {
+	dependsOn 'antora'
 }
 
 jar {
@@ -27,8 +57,19 @@ javadoc {
 	enabled = false
 }
 
+repositories {
+	maven {
+		url "https://repo.spring.io/release"
+	}
+}
+
 dependencies {
-	asciidoctorExtensions "io.spring.asciidoctor.backends:spring-asciidoctor-backends:0.0.5"
+	api(project(":spring-context"))
+	api(project(":spring-web"))
+	api("jakarta.servlet:jakarta.servlet-api")
+
+	implementation(project(":spring-core-test"))
+	implementation("org.assertj:assertj-core")
 }
 
 /**
@@ -82,69 +123,10 @@ rootProject.tasks.dokkaHtmlMultiModule.configure {
 	outputDirectory.set(project.file("$buildDir/docs/kdoc"))
 }
 
-asciidoctorj {
-	version = '2.4.3'
-	fatalWarnings ".*"
-	options doctype: 'book', eruby: 'erubis'
-	attributes([
-			icons: 'font',
-			idprefix: '',
-			idseparator: '-',
-			revnumber: project.version,
-			sectanchors: '',
-			sectnums: '',
-			'spring-version': project.version
-	])
-}
-
-/**
- * Generate the Spring Framework Reference documentation from
- * "src/docs/asciidoc" in "build/docs/ref-docs/html5".
- */
-asciidoctor {
-	baseDirFollowsSourceDir()
-	configurations "asciidoctorExtensions"
-	sources {
-		include '*.adoc'
-	}
-	resources {
-		from(sourceDir) {
-			include 'images/*.png'
-		}
-	}
-	outputDir "$buildDir/docs/ref-docs/html5"
-	outputOptions {
-		backends "spring-html"
-	}
-	forkOptions {
-		jvmArgs += ["--add-opens", "java.base/sun.nio.ch=ALL-UNNAMED", "--add-opens", "java.base/java.io=ALL-UNNAMED"]
-	}
-	logDocuments = true
-}
-
-asciidoctor.mustRunAfter "check"
-
-/**
- * Generate the Spring Framework Reference documentation from "src/docs/asciidoc"
- * in "build/docs/ref-docs/pdf".
- */
-asciidoctorPdf {
-	baseDirFollowsSourceDir()
-	configurations 'asciidoctorExtensions'
-	sources {
-		include 'spring-framework.adocbook'
-	}
-	outputDir "$buildDir/docs/ref-docs/pdf"
-	forkOptions {
-		jvmArgs += ["--add-opens", "java.base/sun.nio.ch=ALL-UNNAMED", "--add-opens", "java.base/java.io=ALL-UNNAMED"]
-	}
-	logDocuments = true
-}
-
 /**
- * Zip all docs (API and reference) into a single archive
+ * Zip all Java docs (javadoc & kdoc) into a single archive
  */
-task docsZip(type: Zip, dependsOn: ['api', 'asciidoctor', 'asciidoctorPdf', rootProject.tasks.dokkaHtmlMultiModule]) {
+task docsZip(type: Zip, dependsOn: ['api', rootProject.tasks.dokkaHtmlMultiModule]) {
 	group = "Distribution"
 	description = "Builds -${archiveClassifier} archive containing api and reference " +
 			"for deployment at https://docs.spring.io/spring-framework/docs/."
@@ -157,12 +139,6 @@ task docsZip(type: Zip, dependsOn: ['api', 'asciidoctor', 'asciidoctorPdf', root
 	from (api) {
 		into "javadoc-api"
 	}
-	from ("$asciidoctor.outputDir") {
-		into "reference/html"
-	}
-	from ("$asciidoctorPdf.outputDir") {
-		into "reference/pdf"
-	}
 	from (rootProject.tasks.dokkaHtmlMultiModule.outputDirectory) {
 		into "kdoc-api"
 	}
@@ -251,4 +227,4 @@ publishing {
 			artifact distZip
 		}
 	}
-}
+}