Antora

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

.gitignore

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

pom.xml

@@ -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,77 +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>
-									<version>${project.version}</version>
-									<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>
 
 						<!--
@@ -416,6 +372,12 @@ limitations under the License.
 
 					</plugins>
 				</pluginManagement>
+				<resources>
+					<resource>
+						<directory>src/docs/antora/resources</directory>
+						<filtering>true</filtering>
+					</resource>
+				</resources>
 			</build>
 		</profile>
 

spring-modulith-distribution/pom.xml

@@ -37,8 +37,8 @@
 				<artifactId>maven-assembly-plugin</artifactId>
 			</plugin>
 			<plugin>
-				<groupId>org.asciidoctor</groupId>
-				<artifactId>asciidoctor-maven-plugin</artifactId>
+				<groupId>io.spring.maven.antora</groupId>
+				<artifactId>antora-maven-plugin</artifactId>
 			</plugin>
 		</plugins>
 	</build>

src/docs/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)

src/docs/antora/antora-playbook.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.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/modules/ROOT/nav.adoc

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

src/docs/asciidoc/90-appendix.adoc → src/docs/antora/modules/ROOT/pages/appendix.adoc

@@ -1,6 +1,6 @@
 [[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]]
@@ -23,7 +23,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`
@@ -101,7 +101,7 @@ a|* `spring-modulith-docs`
 |`spring-modulith-events-jdbc`|`runtime`|A JDBC-based implementation of the `EventPublicationRegistry`.
 |`spring-modulith-events-jpa`|`runtime`|A JPA-based implementation of the `EventPublicationRegistry`.
 |`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>>.
 |===

src/docs/asciidoc/60-documentation.adoc → src/docs/antora/modules/ROOT/pages/documentation.adoc

@@ -246,7 +246,7 @@ _Others_
 It consists of the following sections:
 
 * __The application module's base package.__
-* __The Spring beans exposed by the application module, grouped by stereotype.__ -- In other words, beans that are located in either the API package or any <<fundamentals.modules.named-interfaces, named interface package>>.
+* __The Spring beans exposed by the application module, grouped by stereotype.__ -- In other words, beans that are located in either the API package or any xref:fundamentals.adoc#fundamentals.modules.named-interfaces[named interface package].
 This will detect component stereotypes defined by https://github.com/xmolecules/jmolecules/tree/main/jmolecules-architecture[jMolecules architecture abstractions], but also standard Spring stereotype annotations.
 * __Exposed aggregate roots__ -- Any entities that we find repositories for or explicitly declared as aggregate via jMolecules.
 * __Application events published by the module__ -- Those event types need to be demarcated using jMolecules `@DomainEvent` or implement its `DomainEvent` interface.

src/docs/asciidoc/40-events.adoc → src/docs/antora/modules/ROOT/pages/events.adoc

@@ -1,9 +1,10 @@
 [[events]]
 :imagesdir: images
+[[working-with-application-events]]
 = Working with Application Events
 
 To keep application modules as decoupled as possible from each other, their primary means of interaction should be event publication and consumption.
-This avoids the originating module to know about all potentially interested parties, which is a key aspect to enable application module integration testing (see <<testing>>).
+This avoids the originating module to know about all potentially interested parties, which is a key aspect to enable application module integration testing (see xref:testing.adoc[Integration Testing Application Modules]).
 
 Often we will find application components defined like this:
 
@@ -27,7 +28,7 @@ public class OrderManagement {
 ----
 
 The `complete(…)` method creates functional gravity in the sense that it attracts related functionality and thus interaction with Spring beans defined in other application modules.
-This especially makes the component harder to test as we need to have instances available of those depended on beans just to create an instance of `OrderManagement` (see <<testing.efferent-dependencies>>).
+This especially makes the component harder to test as we need to have instances available of those depended on beans just to create an instance of `OrderManagement` (see xref:testing.adoc#testing.efferent-dependencies[Dealing with Efferent Dependencies]).
 It also means that we will have to touch the class whenever we would like to integrate further functionality with the business event order completion.
 
 We can change the application module interaction as follows:
@@ -127,10 +128,10 @@ image::event-publication-registry-end.png[]
 
 To actually write the event publication log, Spring Modulith exposes an `EventPublicationRepository` SPI and implementations for popular persistence technologies that support transactions, like JPA, JDBC and MongoDB.
 You select the persistence technology to be used by adding the corresponding JAR to your Spring Modulith application.
-We have prepared dedicated <<events.starters, starters>> to ease that task.
+We have prepared dedicated xref:events.adoc#events.starters[starters] to ease that task.
 
 The JDBC-based implementation can create a dedicated table for the event publication log when the respective configuration property (`spring.modulith.events.jdbc-schema-initialization.enabled`) is set to `true`.
-For details, please consult the <<appendix.schemas, schema overview>> in the appendix.
+For details, please consult the xref:appendix.adoc#appendix.schemas[schema overview] in the appendix.
 
 [[events.serialization]]
 == Event Serializer
@@ -160,7 +161,7 @@ class MyConfiguration {
 == Spring Boot Event Registry Starters
 
 Using the transactional event publication log requires a combination of artifacts added to your application.
-To ease that task, Spring Modulith provides starter POMs that are centered around the <<events.publication-repositories, persistence technology>> to be used and default to the Jackson-based `EventSerializer` implementation.
+To ease that task, Spring Modulith provides starter POMs that are centered around the xref:events.adoc#events.publication-repositories[persistence technology] to be used and default to the Jackson-based `EventSerializer` implementation.
 The following starters are available:
 
 * `spring-modulith-starter-jpa` -- Using JPA as persistence technology.

src/docs/asciidoc/10-fundamentals.adoc → src/docs/antora/modules/ROOT/pages/fundamentals.adoc

@@ -87,7 +87,7 @@ package example.inventory;
 ----
 
 In this case code within the __inventory__ module was only allowed to refer to code in the __order__ module (and code not assigned to any module in the first place).
-Find out about how to monitor that in <<verification>>.
+Find out about how to monitor that in xref:verification.adoc[Verifying Application Module Structure].
 
 [[fundamentals.modules.application-modules]]
 === The `ApplicationModules` Type
@@ -132,7 +132,7 @@ Note, how each module is listed and the contained Spring components are identifi
 [[fundamentals.modules.named-interfaces]]
 === Named Interfaces
 
-By default and as described in <<fundamentals.modules.advanced>>, an application module's base package is considered the API package and thus is the only package to allow incoming dependencies from other modules.
+By default and as described in xref:fundamentals.adoc#fundamentals.modules.advanced[Advanced Application Modules], an application module's base package is considered the API package and thus is the only package to allow incoming dependencies from other modules.
 In case you would like to expose additional packages to other modules, you need to use __named interfaces__.
 You achieve that by annotating the `package-info.java` file of those package with `@NamedInterface`.