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

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

‎.gitignore

+4
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

+97-2
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

-4
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

+37
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

+12
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

+17
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

+2-2
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

+1
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

+2
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

‎src/main/antora/modules/ROOT/pages/index.adoc

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
[[spring-data-jpa-reference-documentation]]
2+
= Spring Data JPA
3+
Oliver Gierke; Thomas Darimont; Christoph Strobl; Mark Paluch; Jay Bryant; Greg Turnquist
4+
:revnumber: {version}
5+
:revdate: {localdate}
6+
:feature-scroll: true
7+
8+
(C) 2008-2023 The original authors.
9+
10+
NOTE: Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically.
11+
12+
[[preface]]
13+
== Preface
14+
:page-section-summary-toc: 1
15+
16+
Spring Data JPA provides repository support for the Jakarta Persistence API (JPA). It eases development of applications that need to access JPA data sources.
17+
18+
[[project]]
19+
== Project Metadata
20+
21+
* Version control: https://github.com/spring-projects/spring-data-jpa
22+
* Bugtracker: https://github.com/spring-projects/spring-data-jpa/issues
23+
* Milestone repository: https://repo.spring.io/milestone
24+
* Snapshot repository: https://repo.spring.io/snapshot

‎src/main/antora/modules/ROOT/pages/jpa.adoc

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
[[jpa.repositories]]
2+
= JPA Repositories
3+
:page-section-summary-toc: 1
4+
5+
This chapter points out the specialties for repository support for JPA. This builds on the core repository support explained in {spring-data-commons-docs-url}/repositories.html[Working with Spring Data Repositories]. Make sure you have a sound understanding of the basic concepts explained there.
6+

‎src/main/antora/modules/ROOT/pages/jpa/auditing.adoc

+77
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
[[jpa.auditing]]
2+
= JPA Auditing
3+
4+
Spring Data JPA provides auditing based upon the foundation provided by {spring-data-commons-docs-url}/auditing.html[Spring Data Common's Auditing support].
5+
6+
7+
There is also a convenience base class, `AbstractAuditable`, which you can extend to avoid the need to manually implement the interface methods. Doing so increases the coupling of your domain classes to Spring Data, which might be something you want to avoid. Usually, the annotation-based way of defining auditing metadata is preferred as it is less invasive and more flexible.
8+
9+
10+
[[jpa.auditing.configuration]]
11+
== General Auditing Configuration
12+
13+
Spring Data JPA ships with an entity listener that can be used to trigger the capturing of auditing information. First, you must register the `AuditingEntityListener` to be used for all entities in your persistence contexts inside your `orm.xml` file, as shown in the following example:
14+
15+
.Auditing configuration orm.xml
16+
====
17+
[source, xml]
18+
----
19+
<persistence-unit-metadata>
20+
<persistence-unit-defaults>
21+
<entity-listeners>
22+
<entity-listener class="….data.jpa.domain.support.AuditingEntityListener" />
23+
</entity-listeners>
24+
</persistence-unit-defaults>
25+
</persistence-unit-metadata>
26+
----
27+
====
28+
29+
You can also enable the `AuditingEntityListener` on a per-entity basis by using the `@EntityListeners` annotation, as follows:
30+
31+
====
32+
[source, java]
33+
----
34+
@Entity
35+
@EntityListeners(AuditingEntityListener.class)
36+
public class MyEntity {
37+
38+
}
39+
----
40+
====
41+
42+
NOTE: The auditing feature requires `spring-aspects.jar` to be on the classpath.
43+
44+
With `orm.xml` suitably modified and `spring-aspects.jar` on the classpath, activating auditing functionality is a matter of adding the Spring Data JPA `auditing` namespace element to your configuration, as follows:
45+
46+
.Activating auditing using XML configuration
47+
====
48+
[source, xml]
49+
----
50+
<jpa:auditing auditor-aware-ref="yourAuditorAwareBean" />
51+
----
52+
====
53+
54+
As of Spring Data JPA 1.5, you can enable auditing by annotating a configuration class with the `@EnableJpaAuditing` annotation. You must still modify the `orm.xml` file and have `spring-aspects.jar` on the classpath. The following example shows how to use the `@EnableJpaAuditing` annotation:
55+
56+
.Activating auditing with Java configuration
57+
====
58+
[source, java]
59+
----
60+
@Configuration
61+
@EnableJpaAuditing
62+
class Config {
63+
64+
@Bean
65+
public AuditorAware<AuditableUser> auditorProvider() {
66+
return new AuditorAwareImpl();
67+
}
68+
}
69+
----
70+
====
71+
72+
If you expose a bean of type `AuditorAware` to the `ApplicationContext`, the auditing infrastructure automatically picks it up and uses it to determine the current user to be set on domain types. If you have multiple implementations registered in the `ApplicationContext`, you can select the one to be used by explicitly setting the `auditorAwareRef` attribute of `@EnableJpaAuditing`.
73+
74+
// FIXME: does this need to exist?
75+
// [[jpa.misc]]
76+
// = Miscellaneous Considerations
77+

0 commit comments

Comments
 (0)