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)

.gitignore

@@ -8,3 +8,7 @@ target/
 .sonar4clipse
 *.sonar4clipseExternals
 .DS_Store
+node_modules
+package-lock.json
+package.json
+node

pom.xml

@@ -42,6 +42,16 @@
 
 		<sonar.dynamicAnalysis>reuseReports</sonar.dynamicAnalysis>
 
+		<!-- Antora -->
+		<node.version>v18.12.1</node.version>
+		<npm.version>8.19.2</npm.version>
+		<antora.version>3.2.0-alpha.2</antora.version>
+		<antora-atlas.version>1.0.0-alpha.1</antora-atlas.version>
+		<antora-collector.version>1.0.0-alpha.3</antora-collector.version>
+		<asciidoctor-tabs.version>1.0.0-beta.3</asciidoctor-tabs.version>
+		<spring-antora-extensions.version>1.4.0</spring-antora-extensions.version>
+		<spring-asciidoctor-extensions.version>1.0.0-alpha.9</spring-asciidoctor-extensions.version>
+
 	</properties>
 
 	<modules>
@@ -202,7 +212,6 @@
 					</execution>
 				</executions>
 			</plugin>
-
 		</plugins>
 	</build>
 

spring-data-jpa-distribution/pom.xml

@@ -21,6 +21,7 @@
 	<properties>
 		<project.root>${basedir}/..</project.root>
 		<dist.key>DATAJPA</dist.key>
+
 	</properties>
 
 	<build>
@@ -29,11 +30,96 @@
 				<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>
+	<profiles>
+		<profile>
+			<id>docs</id>
+			<build>
+				<plugins>
+					<plugin>
+						<groupId>com.github.eirslett</groupId>
+						<artifactId>frontend-maven-plugin</artifactId>
+						<version>1.12.1</version>
+						<executions>
+							<execution>
+								<id>install-antora</id>
+								<goals>
+									<goal>install-node-and-npm</goal>
+								</goals>
+								<phase>initialize</phase>
+								<configuration>
+									<nodeVersion>${node.version}</nodeVersion>
+									<npmVersion>${npm.version}</npmVersion>
+								</configuration>
+							</execution>
+							<execution>
+								<id>npm install antora</id>
+								<goals>
+									<goal>npm</goal>
+								</goals>
+								<phase>initialize</phase>
+								<configuration>
+									<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>
+								</configuration>
+							</execution>
+						</executions>
+					</plugin>
+					<plugin>
+						<groupId>org.codehaus.mojo</groupId>
+						<artifactId>exec-maven-plugin</artifactId>
+						<version>3.0.0</version>
+						<executions>
+							<execution>
+								<id>antora</id>
+								<goals>
+									<goal>exec</goal>
+								</goals>
+								<phase>compile</phase>
+								<configuration>
+									<!-- If we don't want to depend on default node installation path we can use a maven
+                                     property aligned with frontend-maven-plugin's installDirectory configuration -->
+									<executable>node/node</executable>
+									<arguments>
+										<argument>node_modules/.bin/antora</argument>
+										<argument>src/main/antora/antora-playbook.yml</argument>
+										<argument>--to-dir=target/site</argument>
+									</arguments>
+									<workingDirectory>${project.parent.basedir}</workingDirectory>
+								</configuration>
+							</execution>
+						</executions>
+					</plugin>
+					<plugin>
+						<groupId>org.apache.maven.plugins</groupId>
+						<artifactId>maven-clean-plugin</artifactId>
+						<version>3.1.0</version>
+						<configuration>
+							<filesets>
+								<fileset>
+									<directory>node</directory>
+									<followSymlinks>false</followSymlinks>
+								</fileset>
+								<fileset>
+									<directory>node_modules</directory>
+									<followSymlinks>false</followSymlinks>
+								</fileset>
+								<fileset>
+									<directory>build</directory>
+									<followSymlinks>false</followSymlinks>
+								</fileset>
+							</filesets>
+						</configuration>
+					</plugin>
+				</plugins>
+				<resources>
+					<resource>
+						<directory>src/main/resources</directory>
+						<filtering>true</filtering>
+					</resource>
+				</resources>
+			</build>
+		</profile>
+	</profiles>
 
 </project>

spring-data-jpa-distribution/src/main/resources/antora-resources/antora.yml

@@ -0,0 +1,11 @@
+version: ${project.version}
+
+asciidoc:
+  attributes:
+    version: ${project.version}
+    springversion: ${spring}
+    attribute-missing: 'warn'
+    spring-data-commons-docs-url: https://rwinch.github.io/spring-data-commons
+    spring-data-commons-javadoc-base: https://docs.spring.io/spring-data/data-commons/docs/current/api/
+    springdocsurl: https://docs.spring.io/spring-framework/docs/${spring}/reference/html
+    springjavadocurl: https://docs.spring.io/spring-framework/docs/${spring}/javadoc-api

src/main/antora/antora-playbook.yml

@@ -0,0 +1,37 @@
+# PACKAGES [email protected] @antora/atlas-extension:1.0.0-alpha.1 @antora/[email protected] @springio/[email protected] @asciidoctor/[email protected] @opendevise/[email protected]
+#
+# The purpose of this Antora playbook is to build the docs in the current branch.
+antora:
+  extensions:
+    - '@antora/collector-extension'
+    - require: '@springio/antora-extensions/root-component-extension'
+      root_component_name: 'data-jpa'
+site:
+  title: Spring Data JPA
+  url: https://docs.spring.io/spring-data-jpa/reference/
+content:
+  sources:
+    - url: ./../../..
+      branches: HEAD
+      start_path: src/main/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.3/ui-bundle.zip
+    snapshot: true

src/main/antora/antora.yml

@@ -0,0 +1,12 @@
+name: data-jpa
+version: true
+title: Spring Data JPA
+nav:
+  - modules/ROOT/nav.adoc
+ext:
+  collector:
+  - run:
+      command: mvnw resources:resources -pl spring-data-jpa-distribution -am -Pdocs
+      local: true
+    scan:
+      dir: spring-data-jpa-distribution/target/classes/antora-resources

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

@@ -0,0 +1,17 @@
+* xref:index.adoc[Overview]
+* xref:jpa.adoc[]
+** xref:jpa/introduction.adoc[]
+** xref:jpa/entity-persistence.adoc[]
+** xref:jpa/query-methods.adoc[]
+** xref:jpa/stored-procedures.adoc[]
+** xref:jpa/specifications.adoc[]
+** xref:jpa/query-by-example.adoc[]
+** xref:jpa/transactions.adoc[]
+** xref:jpa/locking.adoc[]
+** xref:jpa/auditing.adoc[]
+** xref:jpa/misc-context.adoc[]
+** xref:jpa/misc-merging-persistence-units.adoc[]
+** xref:jpa/jpd-misc-cdi-integration.adoc[]
+* xref:envers.adoc[]
+* xref:faq.adoc[]
+* xref:glossary.adoc[]

src/main/asciidoc/envers.adoc → src/main/antora/modules/ROOT/pages/envers.adoc

@@ -189,7 +189,7 @@ class EnversIntegrationTests {
 	}
 }
 ----
-<1> This references the application context configuration presented earlier (in the <<envers.configuration>> section).
+<1> This references the application context configuration presented earlier (in the xref:envers.adoc#envers.configuration[Configuration] section).
 ====
 
 [[envers.resources]]

src/main/asciidoc/faq.adoc → src/main/antora/modules/ROOT/pages/faq.adoc

@@ -1,5 +1,6 @@
 [[faq]]
 [appendix]
+[[frequently-asked-questions]]
 = Frequently Asked Questions
 
 [[faq.common]]

src/main/asciidoc/glossary.adoc → src/main/antora/modules/ROOT/pages/glossary.adoc

@@ -1,6 +1,8 @@
 [[glossary]]
 [appendix, glossary]
+[[glossary]]
 = Glossary
+:page-section-summary-toc: 1
 
 AOP :: Aspect oriented programming
 

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

@@ -0,0 +1,25 @@
+[[spring-data-jpa-reference-documentation]]
+= Spring Data JPA
+Oliver Gierke; Thomas Darimont; Christoph Strobl; Mark Paluch; Jay Bryant; Greg Turnquist
+:revnumber: {version}
+:revdate: {localdate}
+ifdef::backend-epub3[:front-cover-image: image:epub-cover.png[Front Cover,1050,1600]]
+:feature-scroll: true
+
+(C) 2008-2023 The original authors.
+
+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.
+
+[[preface]]
+== Preface
+:page-section-summary-toc: 1
+
+Spring Data JPA provides repository support for the Jakarta Persistence API (JPA). It eases development of applications that need to access JPA data sources.
+
+[[project]]
+== Project Metadata
+
+* Version control: https://github.com/spring-projects/spring-data-jpa
+* Bugtracker: https://github.com/spring-projects/spring-data-jpa/issues
+* Milestone repository: https://repo.spring.io/milestone
+* Snapshot repository: https://repo.spring.io/snapshot

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

@@ -0,0 +1,6 @@
+[[jpa.repositories]]
+= JPA Repositories
+:page-section-summary-toc: 1
+
+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.
+