Migrate to Antora Documentation

* Use `providers.provider` for `modifiedFiles`.
This defers the looking up of `modifiedFiles` until it is used. It
also allows other tasks to be ran from the non-primary work tree.
Working in another work tree is essential for Antora which will clone
each branch/tag into a new work tree to process it.

* Migrate Structure

* Insert explicit ids for headers

* Fix image::image

* Copy default antora files

* Fix indentation for all pages

* Split files

* Generate a default navigation

* Remove includes

* Fix cross references

* Enable Section Summary TOC for small pages

* Polish nav.adoc

* Fix duplicate ids

* Escape {firstname} and {lastname}

* Remove links to htmlsingle and pdf Formats

* Fix broken links

* Disable attributes for ${debezium-version}

* Migrate to Asciidoctor Tabs

* Move to src/reference/antora

* Remove Asciidoctor Build

* deploy-docs only spring-projects

Author: rwinch

.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)

.github/workflows/pr-build-workflow.yml

@@ -36,7 +36,7 @@ jobs:
           debug: false
           concurrent: true
           gradle-build-scan-report: false
-          arguments: checkAsciidocLinks check
+          arguments: check
 
       - name: Capture Test Results
         if: failure()

CONTRIBUTING.adoc

@@ -96,10 +96,10 @@ To build api Javadoc (results will be in `build/api`):
 ./gradlew api
 ----
 
-To build the reference documentation (results will be in `build/docs/asciidoc` and `build/docs/asciidocPdf`):
+To build the reference documentation (results will be in `build/site`):
 
 ----
-./gradlew reference
+./gradlew antora
 ----
 
 To build complete distribution including `-dist`, `-docs`, and `-schema` zip files (results will be in `build/distributions`):

README.md

@@ -58,7 +58,7 @@ Please see our [Security policy](https://github.com/spring-projects/spring-integ
 
 # Documentation
 
-The Spring Integration maintains reference documentation ([published](https://docs.spring.io/spring-integration/docs/current/reference/html/) and [source](src/reference/asciidoc)), GitHub [wiki pages](https://github.com/spring-projects/spring-integration/wiki), and an [API reference](https://docs.spring.io/spring-integration/docs/current/api/). 
+The Spring Integration maintains reference documentation ([published](https://docs.spring.io/spring-integration/reference/) and [source](src/reference/antora)), GitHub [wiki pages](https://github.com/spring-projects/spring-integration/wiki), and an [API reference](https://docs.spring.io/spring-integration/docs/current/api/). 
 There are also [guides and tutorials](https://spring.io/guides) across Spring projects.
 
 
@@ -90,9 +90,9 @@ To build api Javadoc (results will be in `build/api`):
 
     ./gradlew api
 
-To build the reference documentation (results will be in `build/docs/asciidoc` and `build/docs/asciidocPdf`):
+To build the reference documentation (results will be in `build/site`):
 
-    ./gradlew reference
+    ./gradlew antora
 
 To build complete distribution including `-dist`, `-docs`, and `-schema` zip files (results will be in `build/distributions`):
 

build.gradle

@@ -15,14 +15,15 @@ buildscript {
 }
 
 plugins {
+    id 'base'
     id 'org.sonarqube' version '4.3.0.3225'
     id 'io.spring.nohttp' version '0.0.11' apply false
     id 'org.ajoberstar.grgit' version '4.1.1'
     id 'io.spring.dependency-management' version '1.1.2'
     id 'com.jfrog.artifactory' version '4.33.1' apply false
     id 'org.jetbrains.dokka' version "1.8.20"
-    id 'org.asciidoctor.jvm.pdf' version '3.3.2'
-    id 'org.asciidoctor.jvm.convert' version '3.3.2'
+    id 'org.antora' version '1.0.0'
+    id 'io.spring.antora.generate-antora-yml' version '0.0.1'
 }
 
 if (isCI) {
@@ -44,8 +45,8 @@ ext {
     linkScmConnection = 'scm:git:git://github.com/spring-projects/spring-integration.git'
     linkScmDevConnection = 'scm:git:ssh://[email protected]:spring-projects/spring-integration.git'
 
-    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') } }
 
     apacheSshdVersion = '2.10.0'
     artemisVersion = '2.29.0'
@@ -289,7 +290,7 @@ configure(javaProjects) { subproject ->
 
     task updateCopyrights {
         onlyIf { !isCI }
-        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')
 
         doLast {
@@ -337,7 +338,7 @@ configure(javaProjects) { subproject ->
         }
     }
 
-    task testAll(type: Test, dependsOn: [':checkAsciidocLinks', 'check'])
+    task testAll(type: Test, dependsOn: ['check'])
 
     gradle.taskGraph.whenReady { graph ->
         if (graph.hasTask(testAll)) {
@@ -1237,7 +1238,7 @@ task schemaZip(type: Zip) {
     }
 }
 
-task docsZip(type: Zip, dependsOn: [reference, dokkaHtmlMultiModule]) {
+task docsZip(type: Zip, dependsOn: [dokkaHtmlMultiModule]) {
     group = 'Distribution'
     archiveClassifier = 'docs'
     description = "Builds -${archiveClassifier} archive containing api and reference " +
@@ -1251,16 +1252,6 @@ task docsZip(type: Zip, dependsOn: [reference, dokkaHtmlMultiModule]) {
         into 'api'
     }
 
-    from('build/docs/asciidoc') {
-        into 'reference/html'
-    }
-
-    from('build/docs/asciidocPdf') {
-        include 'index-single.pdf'
-        rename 'index-single.pdf', 'spring-integration-reference.pdf'
-        into 'reference/pdf'
-    }
-
     from(dokkaHtmlMultiModule.outputDirectory) {
         into 'kdoc-api'
     }

gradle/docs.gradle

@@ -1,56 +1,46 @@
 ext {
-	backendVersion = '0.0.5'
 	micrometerDocsVersion='1.0.1'
 }
 
+
+antora {
+	version = '3.2.0-alpha.2'
+	playbook = file('src/reference/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 ]
+	} )
+	baseAntoraYmlFile = file('src/reference/antora/antora.yml')
+}
+
+tasks.create(name: 'createAntoraPartials', type: Sync) {
+	from { tasks.filterMetricsDocsContent.outputs }
+	into layout.buildDirectory.dir('generated-antora-resources/modules/ROOT/partials')
+}
+
+tasks.create('generateAntoraResources') {
+	dependsOn 'createAntoraPartials'
+	dependsOn 'generateAntoraYml'
+}
+
 configurations {
-	asciidoctorExtensions
 	micrometerDocs
 }
 
 dependencies {
-	asciidoctorExtensions "io.spring.asciidoctor.backends:spring-asciidoctor-backends:$backendVersion"
 	micrometerDocs "io.micrometer:micrometer-docs-generator:$micrometerDocsVersion"
 }
 
-task checkAsciidocLinks {
-	inputs.dir('src/reference/asciidoc')
-	doLast {
-		def errors = new ArrayList<>();
-		errors.add('*** Anchor reference errors found:')
-		inputs.files.filter{ f -> f.path.endsWith('.adoc') }.each { file ->
-			def doc = file.text
-			def anchors = new HashSet<>()
-			def matcher = (doc =~ /\[\[([^]]+)]]/)
-			while (matcher.find()) {
-				anchors.add(matcher.group(1))
-			}
-			matcher = (doc =~ /<<([^>]+)>>/)
-			while (matcher.find()) {
-				def anchor = matcher.group(1);
-				def hasComma = anchor.contains(',')
-				if (!anchor.startsWith('./')) {
-					if (hasComma) {
-						anchor = anchor.substring(0, anchor.indexOf(","));
-					}
-					if (!anchors.contains(anchor)) {
-						errors.add("\nAnchor '$anchor' not found in '${file.name}', " +
-								"if in another file, it needs to be qualified with './fileName.adoc#'")
-					}
-				}
-				else {
-					if (!hasComma) {
-						errors.add("\nExternal anchor '$anchor' in '${file.name}' should have a textual description (,...)")
-					}
-				}
-			}
-		}
-		if (errors.size() > 1) {
-			throw new InvalidUserDataException(errors.toString())
-		}
-	}
-}
-
 def observationInputDir = file('spring-integration-core/src/main/java/org/springframework/integration/support/management/observation').absolutePath
 def generatedDocsDir = file("$buildDir/reference/generated").absolutePath
 
@@ -69,82 +59,4 @@ task filterMetricsDocsContent(type: Copy) {
 	into generatedDocsDir
 	rename { filename -> filename.replace '_', '' }
 	filter { line -> line.replaceAll('org.springframework.integration', 'o.s.i') }
-}
-
-task prepareDocs(type: Copy) {
-	dependsOn checkAsciidocLinks, filterMetricsDocsContent
-	from 'src/reference/asciidoc'
-	into "$buildDir/reference"
-}
-
-asciidoctorPdf {
-	dependsOn prepareDocs
-
-	forkOptions {
-		jvmArgs '--add-opens', 'java.base/sun.nio.ch=ALL-UNNAMED', '--add-opens', 'java.base/java.io=ALL-UNNAMED'
-	}
-
-	baseDirFollowsSourceFile()
-
-	asciidoctorj {
-		sourceDir "$buildDir/reference"
-		sources {
-			include 'index-single.adoc'
-		}
-		options doctype: 'book'
-		attributes 'icons': 'font',
-				'sectanchors': '',
-				'sectnums': '',
-				'toc': '',
-				'source-highlighter' : 'coderay',
-				revnumber: project.version,
-				'project-version': project.version
-	}
-}
-
-asciidoctor {
-	dependsOn asciidoctorPdf
-
-	forkOptions {
-		jvmArgs '--add-opens', 'java.base/sun.nio.ch=ALL-UNNAMED', '--add-opens', 'java.base/java.io=ALL-UNNAMED'
-	}
-
-	baseDirFollowsSourceFile()
-
-	configurations 'asciidoctorExtensions'
-	sourceDir "$buildDir/reference"
-	outputOptions {
-		backends 'spring-html'
-	}
-	resources {
-		from(sourceDir) {
-			include 'images/*', 'css/**', 'js/**'
-		}
-	}
-
-	options doctype: 'book', eruby: 'erubis'
-	attributes 'docinfo': 'shared',
-			stylesdir: 'css/',
-			stylesheet: 'stylesheet.css',
-			'linkcss': true,
-			'copycss': false,
-			'icons': 'font',
-			'sectanchors': '',
-			'source-highlighter': 'highlight.js',
-			'highlightjsdir': 'js/highlight',
-			'highlightjs-theme': 'github',
-			'idprefix': '',
-			'idseparator': '-',
-			'allow-uri-read': '',
-			'toc': 'left',
-			'toclevels': '4',
-			revnumber: project.version,
-			'project-version': project.version
-}
-
-task reference(dependsOn: asciidoctor) {
-	group = 'Documentation'
-	description = 'Generate the reference documentation'
-}
-
-reference.onlyIf { 'true' != System.env['NO_REFERENCE_TASK'] || project.hasProperty('ignoreEnvToStopReference') }
+}

src/reference/antora/antora-playbook.yml

@@ -0,0 +1,41 @@
+# PACKAGES [email protected] @antora/atlas-extension:1.0.0-alpha.1 @antora/[email protected] @springio/[email protected] @asciidoctor/[email protected] @opendevise/[email protected]
+#
+# The purpose of this Antora playbook is to build the docs in the current branch.
+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: 'integration'
+site:
+  title: Spring Integration
+  url: https://docs.spring.io/spring-integration/reference/
+content:
+  sources:
+    - url: ./../../..
+      branches: HEAD
+      worktrees: true
+      start_path: src/reference/antora
+asciidoc:
+  attributes:
+    page-stackoverflow-url: https://stackoverflow.com/tags/spring-integration
+    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.4/ui-bundle.zip

src/reference/antora/antora.yml

@@ -0,0 +1,20 @@
+name: integration
+version: true
+title: Spring Integration
+nav:
+  - modules/ROOT/nav.adoc
+ext:
+  collector:
+    run:
+      command: gradlew -q "-Dorg.gradle.jvmargs=-Xmx3g -XX:+HeapDumpOnOutOfMemoryError" :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'
+    snippets: example$docs-src/test/java/org/springframework/integration/docs