Skip to content

Commit 2f46906

Browse files
rwinchodrotbohm
rwinch
authored and
odrotbohm
committed
GH-285 - Migrate documentation to Antora.
1 parent 607d046 commit 2f46906

25 files changed

+247
-209
lines changed

‎.github/workflows/deploy-docs.yml

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
name: Deploy Docs
2+
on:
3+
push:
4+
branches-ignore: [ gh-pages ]
5+
tags: '**'
6+
repository_dispatch:
7+
types: request-build-reference # legacy
8+
#schedule:
9+
#- cron: '0 10 * * *' # Once per day at 10am UTC
10+
workflow_dispatch:
11+
permissions: read-all
12+
jobs:
13+
build:
14+
runs-on: ubuntu-latest
15+
if: github.repository_owner == 'spring-projects'
16+
steps:
17+
- name: Checkout
18+
uses: actions/checkout@v3
19+
with:
20+
ref: docs-build
21+
fetch-depth: 1
22+
- name: Dispatch (partial build)
23+
if: github.ref_type == 'branch'
24+
env:
25+
GH_TOKEN: ${{ secrets.GH_ACTIONS_REPO_TOKEN }}
26+
run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD) -f build-refname=${{ github.ref_name }}
27+
- name: Dispatch (full build)
28+
if: github.ref_type == 'tag'
29+
env:
30+
GH_TOKEN: ${{ secrets.GH_ACTIONS_REPO_TOKEN }}
31+
run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD)

‎.github/workflows/docs.yaml

-36
This file was deleted.

‎.gitignore

+6
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,9 @@ changelog.txt
1414
#IntelliJ Stuff
1515
.idea
1616
*.iml
17+
18+
# Antora
19+
node
20+
node_modules
21+
package.json
22+
package-lock.json

‎pom.xml

+23-60
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,6 @@
4141
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
4242
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
4343
<spring.version>6.0.11</spring.version> <!-- For Javadoc links only -->
44-
<spring-asciidoctor-backends.version>0.0.7</spring-asciidoctor-backends.version>
4544
<spring-boot.version>3.2.0-M2</spring-boot.version>
4645

4746
</properties>
@@ -277,76 +276,34 @@ limitations under the License.
277276
<plugins>
278277

279278
<!--
280-
Asciidoctor
279+
Antora
281280
-->
282281

283282
<plugin>
284-
<groupId>org.asciidoctor</groupId>
285-
<artifactId>asciidoctor-maven-plugin</artifactId>
286-
<version>2.2.2</version>
287-
<dependencies>
288-
<dependency>
289-
<groupId>org.jruby</groupId>
290-
<artifactId>jruby</artifactId>
291-
<version>9.3.7.0</version>
292-
</dependency>
293-
<dependency>
294-
<groupId>org.asciidoctor</groupId>
295-
<artifactId>asciidoctorj</artifactId>
296-
<version>2.5.7</version>
297-
</dependency>
298-
<dependency>
299-
<groupId>org.asciidoctor</groupId>
300-
<artifactId>asciidoctorj-diagram</artifactId>
301-
<version>2.2.3</version>
302-
</dependency>
303-
<dependency>
304-
<groupId>io.spring.asciidoctor.backends</groupId>
305-
<artifactId>spring-asciidoctor-backends</artifactId>
306-
<version>${spring-asciidoctor-backends.version}</version>
307-
</dependency>
308-
</dependencies>
309-
283+
<groupId>io.spring.maven.antora</groupId>
284+
<artifactId>antora-component-version-maven-plugin</artifactId>
285+
<version>0.0.4</version>
310286
<executions>
311-
312287
<execution>
313-
<id>html</id>
314-
<phase>generate-resources</phase>
315288
<goals>
316-
<goal>process-asciidoc</goal>
289+
<goal>antora-component-version</goal>
317290
</goals>
318-
<configuration>
319-
<backend>spring-html</backend>
320-
<sourceDirectory>../src/docs/asciidoc</sourceDirectory>
321-
<sourceDocumentName>index.adoc</sourceDocumentName>
322-
<outputDirectory>${generated-docs.directory}/html</outputDirectory>
323-
<attributes>
324-
<source-highlighter>highlight.js</source-highlighter>
325-
<highlightjsdir>js/highlight</highlightjsdir>
326-
<highlightjs-theme>github</highlightjs-theme>
327-
</attributes>
328-
</configuration>
329291
</execution>
330292
</executions>
331-
293+
</plugin>
294+
<plugin>
295+
<groupId>io.spring.maven.antora</groupId>
296+
<artifactId>antora-maven-plugin</artifactId>
297+
<version>0.0.4</version>
298+
<extensions>true</extensions>
332299
<configuration>
333-
<doctype>book</doctype>
334-
<attributes>
335-
<docinfo>shared</docinfo>
336-
<icons>font</icons>
337-
<sectids>false</sectids>
338-
<imagesdir>images</imagesdir>
339-
<projectName>${project.name}</projectName>
340-
<projectVersion>${project.version}</projectVersion>
341-
<springVersion>${spring.version}</springVersion>
342-
<toclevels>4</toclevels>
343-
<numbered>true</numbered>
344-
</attributes>
345-
<requires>
346-
<require>asciidoctor-diagram</require>
347-
</requires>
300+
<playbook>../src/docs/antora/antora-playbook.yml</playbook>
301+
<options>
302+
<option>--to-dir=target/antora/site</option>
303+
<option>--stacktrace</option>
304+
<option>--fetch</option>
305+
</options>
348306
</configuration>
349-
350307
</plugin>
351308

352309
<!--
@@ -415,6 +372,12 @@ limitations under the License.
415372

416373
</plugins>
417374
</pluginManagement>
375+
<resources>
376+
<resource>
377+
<directory>src/docs/antora/resources</directory>
378+
<filtering>true</filtering>
379+
</resource>
380+
</resources>
418381
</build>
419382
</profile>
420383

‎spring-modulith-distribution/pom.xml

-4
Original file line numberDiff line numberDiff line change
@@ -36,10 +36,6 @@
3636
<groupId>org.apache.maven.plugins</groupId>
3737
<artifactId>maven-assembly-plugin</artifactId>
3838
</plugin>
39-
<plugin>
40-
<groupId>org.asciidoctor</groupId>
41-
<artifactId>asciidoctor-maven-plugin</artifactId>
42-
</plugin>
4339
</plugins>
4440
</build>
4541

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

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: Deploy Docs
2+
on:
3+
push:
4+
branches-ignore: [ gh-pages ]
5+
tags: '**'
6+
repository_dispatch:
7+
types: request-build-reference # legacy
8+
#schedule:
9+
#- cron: '0 10 * * *' # Once per day at 10am UTC
10+
workflow_dispatch:
11+
permissions:
12+
actions: write
13+
jobs:
14+
build:
15+
runs-on: ubuntu-latest
16+
# FIXME: enable when pushed to spring-projects
17+
# if: github.repository_owner == 'spring-projects'
18+
steps:
19+
- name: Checkout
20+
uses: actions/checkout@v3
21+
with:
22+
ref: docs-build
23+
fetch-depth: 1
24+
- name: Dispatch (partial build)
25+
if: github.ref_type == 'branch'
26+
env:
27+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
28+
run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD) -f build-refname=${{ github.ref_name }}
29+
- name: Dispatch (full build)
30+
if: github.ref_type == 'tag'
31+
env:
32+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
33+
run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD)

‎src/docs/antora/antora-playbook.yml

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
antora:
2+
extensions:
3+
- '@springio/antora-extensions/partial-build-extension'
4+
- require: '@springio/antora-extensions/latest-version-extension'
5+
- require: '@springio/antora-extensions/inject-collector-cache-config-extension'
6+
- '@antora/collector-extension'
7+
- '@antora/atlas-extension'
8+
- require: '@springio/antora-extensions/root-component-extension'
9+
root_component_name: 'modulith'
10+
site:
11+
title: Spring Modulith
12+
url: https://docs.spring.io/spring-modulith/reference/
13+
content:
14+
sources:
15+
- url: ./../../..
16+
branches: HEAD
17+
start_path: src/docs/antora
18+
worktrees: true
19+
asciidoc:
20+
attributes:
21+
page-pagination: ''
22+
hide-uri-scheme: '@'
23+
tabs-sync-option: '@'
24+
chomp: 'all'
25+
extensions:
26+
- '@asciidoctor/tabs'
27+
- '@springio/asciidoctor-extensions'
28+
sourcemap: true
29+
urls:
30+
latest_version_segment: ''
31+
runtime:
32+
log:
33+
failure_level: warn
34+
format: pretty
35+
ui:
36+
bundle:
37+
url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.3.5/ui-bundle.zip

‎src/docs/antora/antora.yml

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
name: modulith
2+
version: true
3+
title: Spring Modulith
4+
nav:
5+
- modules/ROOT/nav.adoc
6+
ext:
7+
collector:
8+
run:
9+
command: mvnw -N antora-component-version:antora-component-version resources:resources -am -Pdocumentation
10+
local: true
11+
scan:
12+
dir: target/classes/antora-resources/
13+
14+
asciidoc:
15+
attributes:
16+
attribute-missing: 'warn'
17+
chomp: 'all'

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

File renamed without changes.

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

File renamed without changes.

‎src/docs/asciidoc/images/observability.png renamed to ‎src/docs/antora/modules/ROOT/assets/images/observability.png

File renamed without changes.

‎src/docs/antora/modules/ROOT/nav.adoc

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
* xref:index.adoc[Overview]
2+
* xref:fundamentals.adoc[]
3+
* xref:verification.adoc[]
4+
* xref:events.adoc[]
5+
* xref:testing.adoc[]
6+
* xref:moments.adoc[]
7+
* xref:documentation.adoc[]
8+
* xref:runtime.adoc[]
9+
* xref:production-ready.adoc[]
10+
* xref:appendix.adoc[]

‎src/docs/asciidoc/90-appendix.adoc renamed to ‎src/docs/antora/modules/ROOT/pages/appendix.adoc

+11-11
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
[[appendix]]
22
= Appendix
3-
:jdbc-schema-base: ../../../spring-modulith-events/spring-modulith-events-jdbc/src/main/resources
3+
:jdbc-schema-base: partial$spring-modulith-events-jdbc-src/main/resources
44

55
[appendix]
6-
[[appendix.configuration-properties]]
6+
[[configuration-properties]]
77
== Spring Modulith Configuration Properties
88
[cols="2,1,3", options="header, unbreakable"]
99
|===
@@ -31,7 +31,7 @@
3131

3232
|`spring.modulith.moments.enableTimeMachine`
3333
|`false`
34-
|Whether to enable the <<moments, `TimeMachine`>>.
34+
|Whether to enable the xref:moments.adoc[`TimeMachine`].
3535

3636
|`spring.modulith.moments.granularity`
3737
|`HOURS`
@@ -51,7 +51,7 @@
5151
|===
5252

5353
[appendix]
54-
[[appendix.artifacts]]
54+
[[artifacts]]
5555
== Spring Modulith modules
5656

5757
.Spring Modulith starter POMs
@@ -119,43 +119,43 @@ a|* `spring-modulith-docs`
119119
|`spring-modulith-events-jpa`|`runtime`|A JPA-based implementation of the `EventPublicationRegistry`.
120120
|`spring-modulith-events-kafka`|`runtime`|Event externalization support for Kafka.
121121
|`spring-modulith-events-mongodb`|`runtime`|A MongoDB-based implementation of the `EventPublicationRegistry`.
122-
|`spring-modulith-moments`|`compile`|The Passage of Time events implementation described <<moments, here>>.
122+
|`spring-modulith-moments`|`compile`|The Passage of Time events implementation described xref:moments.adoc[here].
123123
|`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`.
124124
|`spring-modulith-observability`|`runtime`|Observability infrastructure described <<observability, here>>.
125125
|===
126126

127127
[appendix]
128-
[[appendix.schemas]]
128+
[[schemas]]
129129
== Event publication registry schemas
130130

131131
The JDBC-based event publication registry support expects the following database schemas to be present in the database.
132132
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`.
133133

134-
[[appendix.schemas.h2]]
134+
[[schemas.h2]]
135135
=== H2
136136

137137
[source, sql]
138138
----
139139
include::{jdbc-schema-base}/schema-h2.sql[]
140140
----
141141

142-
[[appendix.schemas.hsqldb]]
142+
[[schemas.hsqldb]]
143143
=== HSQLDB
144144

145145
[source, sql]
146146
----
147147
include::{jdbc-schema-base}/schema-hsqldb.sql[]
148148
----
149149

150-
[[appendix.schemas.mysql]]
150+
[[schemas.mysql]]
151151
=== MySQL
152152

153153
[source, sql]
154154
----
155155
include::{jdbc-schema-base}/schema-mysql.sql[]
156156
----
157157

158-
[[appendix.schemas.postgresql]]
158+
[[schemas.postgresql]]
159159
=== PostgreSQL
160160

161161
[source, sql]
@@ -164,7 +164,7 @@ include::{jdbc-schema-base}/schema-postgresql.sql[]
164164
----
165165

166166
[appendix]
167-
[[appendix.migrating-from-moduliths]]
167+
[[migrating-from-moduliths]]
168168
== Migrating from Moduliths
169169

170170

0 commit comments

Comments
 (0)