GH-285 - Migrate documentation to Antora.

Author: rwinch

.github/workflows/deploy-docs.yml

@@ -0,0 +1,31 @@
+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: read-all
+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.GH_ACTIONS_REPO_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.GH_ACTIONS_REPO_TOKEN }}
+      run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD)

.github/workflows/docs.yaml

@@ -14,3 +14,9 @@ changelog.txt
 #IntelliJ Stuff
 .idea
 *.iml
+
+# Antora
+node
+node_modules
+package.json
+package-lock.json

.gitignore

@@ -41,7 +41,6 @@
 		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
 		<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
 		<spring.version>6.0.11</spring.version> <!-- For Javadoc links only -->
-		<spring-asciidoctor-backends.version>0.0.7</spring-asciidoctor-backends.version>
 		<spring-boot.version>3.2.0-M2</spring-boot.version>
 
 	</properties>
@@ -277,76 +276,34 @@ limitations under the License.
 					<plugins>
 
 						<!--
-							Asciidoctor
+							Antora
 						-->
 
 						<plugin>
-							<groupId>org.asciidoctor</groupId>
-							<artifactId>asciidoctor-maven-plugin</artifactId>
-							<version>2.2.2</version>
-							<dependencies>
-								<dependency>
-									<groupId>org.jruby</groupId>
-									<artifactId>jruby</artifactId>
-									<version>9.3.7.0</version>
-								</dependency>
-								<dependency>
-									<groupId>org.asciidoctor</groupId>
-									<artifactId>asciidoctorj</artifactId>
-									<version>2.5.7</version>
-								</dependency>
-								<dependency>
-									<groupId>org.asciidoctor</groupId>
-									<artifactId>asciidoctorj-diagram</artifactId>
-									<version>2.2.3</version>
-								</dependency>
-								<dependency>
-									<groupId>io.spring.asciidoctor.backends</groupId>
-									<artifactId>spring-asciidoctor-backends</artifactId>
-									<version>${spring-asciidoctor-backends.version}</version>
-								</dependency>
-							</dependencies>
-
+							<groupId>io.spring.maven.antora</groupId>
+							<artifactId>antora-component-version-maven-plugin</artifactId>
+							<version>0.0.4</version>
 							<executions>
-
 								<execution>
-									<id>html</id>
-									<phase>generate-resources</phase>
 									<goals>
-										<goal>process-asciidoc</goal>
+										<goal>antora-component-version</goal>
 									</goals>
-									<configuration>
-										<backend>spring-html</backend>
-										<sourceDirectory>../src/docs/asciidoc</sourceDirectory>
-										<sourceDocumentName>index.adoc</sourceDocumentName>
-										<outputDirectory>${generated-docs.directory}/html</outputDirectory>
-										<attributes>
-											<source-highlighter>highlight.js</source-highlighter>
-											<highlightjsdir>js/highlight</highlightjsdir>
-											<highlightjs-theme>github</highlightjs-theme>
-										</attributes>
-									</configuration>
 								</execution>
 							</executions>
-
+						</plugin>
+						<plugin>
+							<groupId>io.spring.maven.antora</groupId>
+							<artifactId>antora-maven-plugin</artifactId>
+							<version>0.0.4</version>
+							<extensions>true</extensions>
 							<configuration>
-								<doctype>book</doctype>
-								<attributes>
-									<docinfo>shared</docinfo>
-									<icons>font</icons>
-									<sectids>false</sectids>
-									<imagesdir>images</imagesdir>
-									<projectName>${project.name}</projectName>
-									<projectVersion>${project.version}</projectVersion>
-									<springVersion>${spring.version}</springVersion>
-									<toclevels>4</toclevels>
-									<numbered>true</numbered>
-								</attributes>
-								<requires>
-									<require>asciidoctor-diagram</require>
-								</requires>
+								<playbook>../src/docs/antora/antora-playbook.yml</playbook>
+								<options>
+									<option>--to-dir=target/antora/site</option>
+									<option>--stacktrace</option>
+									<option>--fetch</option>
+								</options>
 							</configuration>
-
 						</plugin>
 
 						<!--
@@ -415,6 +372,12 @@ limitations under the License.
 
 					</plugins>
 				</pluginManagement>
+				<resources>
+					<resource>
+						<directory>src/docs/antora/resources</directory>
+						<filtering>true</filtering>
+					</resource>
+				</resources>
 			</build>
 		</profile>
 

pom.xml

@@ -36,10 +36,6 @@
 				<groupId>org.apache.maven.plugins</groupId>
 				<artifactId>maven-assembly-plugin</artifactId>
 			</plugin>
-			<plugin>
-				<groupId>org.asciidoctor</groupId>
-				<artifactId>asciidoctor-maven-plugin</artifactId>
-			</plugin>
 		</plugins>
 	</build>
 

spring-modulith-distribution/pom.xml

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

src/docs/antora/.github/workflows/deploy-docs.yml

@@ -0,0 +1,37 @@
+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: 'modulith'
+site:
+  title: Spring Modulith
+  url: https://docs.spring.io/spring-modulith/reference/
+content:
+  sources:
+    - url: ./../../..
+      branches: HEAD
+      start_path: src/docs/antora
+      worktrees: true
+asciidoc:
+  attributes:
+    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

src/docs/antora/antora-playbook.yml

@@ -0,0 +1,17 @@
+name: modulith
+version: true
+title: Spring Modulith
+nav:
+  - modules/ROOT/nav.adoc
+ext:
+  collector:
+    run:
+      command: mvnw -N antora-component-version:antora-component-version resources:resources -am -Pdocumentation
+      local: true
+    scan:
+      dir: target/classes/antora-resources/
+
+asciidoc:
+  attributes:
+    attribute-missing: 'warn'
+    chomp: 'all'

src/docs/antora/antora.yml

@@ -0,0 +1,10 @@
+* xref:index.adoc[Overview]
+* xref:fundamentals.adoc[]
+* xref:verification.adoc[]
+* xref:events.adoc[]
+* xref:testing.adoc[]
+* xref:moments.adoc[]
+* xref:documentation.adoc[]
+* xref:runtime.adoc[]
+* xref:production-ready.adoc[]
+* xref:appendix.adoc[]

src/docs/asciidoc/images/event-publication-registry-end.png renamed to src/docs/antora/modules/ROOT/assets/images/event-publication-registry-end.png

@@ -1,9 +1,9 @@
 [[appendix]]
 = Appendix
-:jdbc-schema-base: ../../../spring-modulith-events/spring-modulith-events-jdbc/src/main/resources
+:jdbc-schema-base: partial$spring-modulith-events-jdbc-src/main/resources
 
 [appendix]
-[[appendix.configuration-properties]]
+[[configuration-properties]]
 == Spring Modulith Configuration Properties
 [cols="2,1,3", options="header, unbreakable"]
 |===
@@ -31,7 +31,7 @@
 
 |`spring.modulith.moments.enableTimeMachine`
 |`false`
-|Whether to enable the <<moments, `TimeMachine`>>.
+|Whether to enable the xref:moments.adoc[`TimeMachine`].
 
 |`spring.modulith.moments.granularity`
 |`HOURS`
@@ -51,7 +51,7 @@
 |===
 
 [appendix]
-[[appendix.artifacts]]
+[[artifacts]]
 == Spring Modulith modules
 
 .Spring Modulith starter POMs
@@ -119,43 +119,43 @@ a|* `spring-modulith-docs`
 |`spring-modulith-events-jpa`|`runtime`|A JPA-based implementation of the `EventPublicationRegistry`.
 |`spring-modulith-events-kafka`|`runtime`|Event externalization support for Kafka.
 |`spring-modulith-events-mongodb`|`runtime`|A MongoDB-based implementation of the `EventPublicationRegistry`.
-|`spring-modulith-moments`|`compile`|The Passage of Time events implementation described <<moments, here>>.
+|`spring-modulith-moments`|`compile`|The Passage of Time events implementation described xref:moments.adoc[here].
 |`spring-modulith-runtime`|`runtime`|Support to bootstrap an `ApplicationModules` instance at runtime. Usually not directly depended on but transitively used by `spring-modulith-actuator` and `spring-modulith-observability`.
 |`spring-modulith-observability`|`runtime`|Observability infrastructure described <<observability, here>>.
 |===
 
 [appendix]
-[[appendix.schemas]]
+[[schemas]]
 == Event publication registry schemas
 
 The JDBC-based event publication registry support expects the following database schemas to be present in the database.
 If you would like Spring Modulith to create the schema for you, set the application property `spring.modulith.events.jdbc-schema-initialization.enabled` to `true`.
 
-[[appendix.schemas.h2]]
+[[schemas.h2]]
 === H2
 
 [source, sql]
 ----
 include::{jdbc-schema-base}/schema-h2.sql[]
 ----
 
-[[appendix.schemas.hsqldb]]
+[[schemas.hsqldb]]
 === HSQLDB
 
 [source, sql]
 ----
 include::{jdbc-schema-base}/schema-hsqldb.sql[]
 ----
 
-[[appendix.schemas.mysql]]
+[[schemas.mysql]]
 === MySQL
 
 [source, sql]
 ----
 include::{jdbc-schema-base}/schema-mysql.sql[]
 ----
 
-[[appendix.schemas.postgresql]]
+[[schemas.postgresql]]
 === PostgreSQL
 
 [source, sql]
@@ -164,7 +164,7 @@ include::{jdbc-schema-base}/schema-postgresql.sql[]
 ----
 
 [appendix]
-[[appendix.migrating-from-moduliths]]
+[[migrating-from-moduliths]]
 == Migrating from Moduliths