Skip to content

Commit 454ce52

Browse files
rwinchgregturn
rwinch
authored and
gregturn
committed
Implement Antora-based reference docs.
See #3080
1 parent b91fd82 commit 454ce52

31 files changed

+1739
-1567
lines changed

‎.github/workflows/deploy-docs.yml

Lines changed: 33 additions & 0 deletions
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)

‎.gitignore

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,3 +8,7 @@ target/
88
.sonar4clipse
99
*.sonar4clipseExternals
1010
.DS_Store
11+
node_modules
12+
package-lock.json
13+
package.json
14+
node

‎pom.xml

Lines changed: 97 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,16 @@
4242

4343
<sonar.dynamicAnalysis>reuseReports</sonar.dynamicAnalysis>
4444

45+
<!-- Antora -->
46+
<node.version>v18.12.1</node.version>
47+
<npm.version>8.19.2</npm.version>
48+
<antora.version>3.2.0-alpha.2</antora.version>
49+
<antora-atlas.version>1.0.0-alpha.1</antora-atlas.version>
50+
<antora-collector.version>1.0.0-alpha.3</antora-collector.version>
51+
<asciidoctor-tabs.version>1.0.0-beta.3</asciidoctor-tabs.version>
52+
<spring-antora-extensions.version>1.4.0</spring-antora-extensions.version>
53+
<spring-asciidoctor-extensions.version>1.0.0-alpha.9</spring-asciidoctor-extensions.version>
54+
4555
</properties>
4656

4757
<modules>
@@ -101,7 +111,93 @@
101111
<eclipselink>4.0.0</eclipselink>
102112
</properties>
103113
</profile>
104-
114+
<profile>
115+
<id>docs</id>
116+
<build>
117+
<plugins>
118+
<plugin>
119+
<groupId>com.github.eirslett</groupId>
120+
<artifactId>frontend-maven-plugin</artifactId>
121+
<version>1.12.1</version>
122+
<executions>
123+
<execution>
124+
<id>install-antora</id>
125+
<goals>
126+
<goal>install-node-and-npm</goal>
127+
</goals>
128+
<phase>initialize</phase>
129+
<configuration>
130+
<nodeVersion>${node.version}</nodeVersion>
131+
<npmVersion>${npm.version}</npmVersion>
132+
</configuration>
133+
</execution>
134+
<execution>
135+
<id>npm install antora</id>
136+
<goals>
137+
<goal>npm</goal>
138+
</goals>
139+
<phase>initialize</phase>
140+
<configuration>
141+
<arguments>install @antora/cli@${antora.version} @antora/site-generator-default@${antora.version} @antora/atlas-extension@${antora-atlas.version} @antora/collector-extension@${antora-collector.version} @asciidoctor/tabs@${asciidoctor-tabs.version} @springio/antora-extensions@${spring-antora-extensions.version} @springio/asciidoctor-extensions@${spring-asciidoctor-extensions.version}</arguments>
142+
</configuration>
143+
</execution>
144+
</executions>
145+
</plugin>
146+
<plugin>
147+
<groupId>org.codehaus.mojo</groupId>
148+
<artifactId>exec-maven-plugin</artifactId>
149+
<version>3.0.0</version>
150+
<executions>
151+
<execution>
152+
<id>antora</id>
153+
<goals>
154+
<goal>exec</goal>
155+
</goals>
156+
<phase>compile</phase>
157+
<configuration>
158+
<!-- If we don't want to depend on default node installation path we can use a maven
159+
property aligned with frontend-maven-plugin's installDirectory configuration -->
160+
<executable>node/node</executable>
161+
<arguments>
162+
<argument>node_modules/.bin/antora</argument>
163+
<argument>src/main/antora/antora-playbook.yml</argument>
164+
<argument>--to-dir=target/site</argument>
165+
</arguments>
166+
<workingDirectory>${project.parent.basedir}</workingDirectory>
167+
</configuration>
168+
</execution>
169+
</executions>
170+
</plugin>
171+
<plugin>
172+
<groupId>org.apache.maven.plugins</groupId>
173+
<artifactId>maven-clean-plugin</artifactId>
174+
<version>3.1.0</version>
175+
<configuration>
176+
<filesets>
177+
<fileset>
178+
<directory>node</directory>
179+
<followSymlinks>false</followSymlinks>
180+
</fileset>
181+
<fileset>
182+
<directory>node_modules</directory>
183+
<followSymlinks>false</followSymlinks>
184+
</fileset>
185+
<fileset>
186+
<directory>build</directory>
187+
<followSymlinks>false</followSymlinks>
188+
</fileset>
189+
</filesets>
190+
</configuration>
191+
</plugin>
192+
</plugins>
193+
<resources>
194+
<resource>
195+
<directory>src/main/resources</directory>
196+
<filtering>true</filtering>
197+
</resource>
198+
</resources>
199+
</build>
200+
</profile>
105201
</profiles>
106202

107203
<dependencyManagement>
@@ -202,7 +298,6 @@
202298
</execution>
203299
</executions>
204300
</plugin>
205-
206301
</plugins>
207302
</build>
208303

‎spring-data-jpa-distribution/pom.xml

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -29,10 +29,6 @@
2929
<groupId>org.apache.maven.plugins</groupId>
3030
<artifactId>maven-assembly-plugin</artifactId>
3131
</plugin>
32-
<plugin>
33-
<groupId>org.asciidoctor</groupId>
34-
<artifactId>asciidoctor-maven-plugin</artifactId>
35-
</plugin>
3632
</plugins>
3733
</build>
3834

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

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# PACKAGES [email protected] @antora/atlas-extension:1.0.0-alpha.1 @antora/[email protected] @springio/[email protected] @asciidoctor/[email protected] @opendevise/[email protected]
2+
#
3+
# The purpose of this Antora playbook is to build the docs in the current branch.
4+
antora:
5+
extensions:
6+
- '@antora/collector-extension'
7+
- require: '@springio/antora-extensions/root-component-extension'
8+
root_component_name: 'data-jpa'
9+
site:
10+
title: Spring Data JPA
11+
url: https://docs.spring.io/spring-data-jpa/reference/
12+
content:
13+
sources:
14+
- url: ./../../..
15+
branches: HEAD
16+
start_path: src/main/antora
17+
worktrees: true
18+
asciidoc:
19+
attributes:
20+
page-pagination: ''
21+
hide-uri-scheme: '@'
22+
tabs-sync-option: '@'
23+
chomp: 'all'
24+
extensions:
25+
- '@asciidoctor/tabs'
26+
- '@springio/asciidoctor-extensions'
27+
sourcemap: true
28+
urls:
29+
latest_version_segment: ''
30+
runtime:
31+
log:
32+
failure_level: warn
33+
format: pretty
34+
ui:
35+
bundle:
36+
url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.3.3/ui-bundle.zip
37+
snapshot: true

‎src/main/antora/antora.yml

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
name: data-jpa
2+
version: true
3+
title: Spring Data JPA
4+
nav:
5+
- modules/ROOT/nav.adoc
6+
ext:
7+
collector:
8+
- run:
9+
command: mvnw -Pdocs resources:resources
10+
local: true
11+
scan:
12+
dir: target/classes/antora-resources

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

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
* xref:index.adoc[Overview]
2+
* xref:jpa.adoc[]
3+
** xref:jpa/introduction.adoc[]
4+
** xref:jpa/entity-persistence.adoc[]
5+
** xref:jpa/query-methods.adoc[]
6+
** xref:jpa/stored-procedures.adoc[]
7+
** xref:jpa/specifications.adoc[]
8+
** xref:jpa/query-by-example.adoc[]
9+
** xref:jpa/transactions.adoc[]
10+
** xref:jpa/locking.adoc[]
11+
** xref:jpa/auditing.adoc[]
12+
** xref:jpa/misc-context.adoc[]
13+
** xref:jpa/misc-merging-persistence-units.adoc[]
14+
** xref:jpa/jpd-misc-cdi-integration.adoc[]
15+
* xref:envers.adoc[]
16+
* xref:faq.adoc[]
17+
* xref:glossary.adoc[]

‎src/main/asciidoc/envers.adoc renamed to ‎src/main/antora/modules/ROOT/pages/envers.adoc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -189,7 +189,7 @@ class EnversIntegrationTests {
189189
}
190190
}
191191
----
192-
<1> This references the application context configuration presented earlier (in the <<envers.configuration>> section).
192+
<1> This references the application context configuration presented earlier (in the xref:envers.adoc#envers.configuration[Configuration] section).
193193
====
194194

195195
[[envers.resources]]
@@ -201,4 +201,4 @@ You should also check out the {spring-data-commons-javadoc-base}/org/springframe
201201

202202
You can ask questions at https://stackoverflow.com/questions/tagged/spring-data-envers[Stackoverflow by using the `spring-data-envers` tag].
203203

204-
The https://github.com/spring-projects/spring-data-envers[source code and issue tracker for Spring Data Envers is hosted at GitHub].
204+
The https://github.com/spring-projects/spring-data-jpa[source code and issue tracker for Spring Data Envers is hosted at GitHub] (as a module of Spring Data JPA).

‎src/main/asciidoc/faq.adoc renamed to ‎src/main/antora/modules/ROOT/pages/faq.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
[[faq]]
22
[appendix]
3+
[[frequently-asked-questions]]
34
= Frequently Asked Questions
45

56
[[faq.common]]

‎src/main/asciidoc/glossary.adoc renamed to ‎src/main/antora/modules/ROOT/pages/glossary.adoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
[[glossary]]
22
[appendix, glossary]
3+
[[glossary]]
34
= Glossary
5+
:page-section-summary-toc: 1
46

57
AOP :: Aspect oriented programming
68

0 commit comments

Comments
 (0)