Migrate documentation to Antora.

Author: meistermeier

.gitignore

@@ -32,3 +32,10 @@ target/
 .flattened-pom.xml
 dependency-reduced-pom.xml
 .gradle
+
+build/
+node_modules
+node
+package.json
+package-lock.json
+

README.adoc

@@ -146,14 +146,14 @@ class MyService {
 
 === Building SDN
 
-Please have a look at the documentation: https://docs.spring.io/spring-data/neo4j/docs/current/reference/html/#building-sdn-rx[Building SDN].
+Please have a look at the documentation: https://docs.spring.io/spring-data/neo4j/reference/#building-sdn-rx[Building SDN].
 
 == Getting Help
 
 Having trouble with Spring Data? We’d love to help!
 
 * Check the
-https://docs.spring.io/spring-data/neo4j/docs/current/reference/html/[reference documentation], and https://docs.spring.io/spring-data/neo4j/docs/current/api/[Javadocs].
+https://docs.spring.io/spring-data/neo4j/reference/[reference documentation], and https://docs.spring.io/spring-data/neo4j/docs/current/api/[Javadocs].
 * Learn the Spring basics – Spring Data builds on Spring Framework, check the https://spring.io[spring.io] web-site for a wealth of reference documentation.
 If you are just starting out with Spring, try one of the https://spring.io/guides[guides].
 * If you are upgrading, check out the https://docs.spring.io/spring-data/neo4j/docs/current/changelog.txt[changelog] for "`new and noteworthy`" features.
@@ -166,7 +166,7 @@ Spring Data uses GitHub as issue tracking system to record bugs and feature requ
 
 * Before you log a bug, please search the
 https://github.com/spring-projects/spring-data-neo4j/issues[issue tracker] to see if someone has already reported the problem.
-* If the issue doesn’t already exist, https://github.com/spring-projects/spring-data-neo4j/issues/new[create a new issue].
+* If the issue doesn't already exist, https://github.com/spring-projects/spring-data-neo4j/issues/new[create a new issue].
 * Please provide as much information as possible with the issue report, we like to know the version of Spring Data Neo4j, the database version and the JVM version that you are using.
 * If you need to paste code, or include a stack trace use Markdown +++```+++ escapes before and after your text.
 * If possible try to create a test-case or project that replicates the issue. Attach a link to your code or a compressed file containing your code.

pom.xml

@@ -68,10 +68,9 @@
 	</developers>
 
 	<properties>
+		<antora.playbook>${project.basedir}/src/main/antora/antora-playbook.yml</antora.playbook>
 		<apiguardian.version>1.1.1</apiguardian.version>
 		<archunit.version>0.23.1</archunit.version>
-		<asciidoctor-maven-plugin.version>2.1.0</asciidoctor-maven-plugin.version>
-		<asciidoctorj-diagram.version>2.1.0</asciidoctorj-diagram.version>
 		<blockhound.version>1.0.8.RELEASE</blockhound.version>
 		<byte-buddy.version>1.14.3</byte-buddy.version>
 		<cdi>3.0.1</cdi>
@@ -115,7 +114,6 @@
 
 		<skipUnitTests>${skipTests}</skipUnitTests>
 
-		<spring-data-commons-docs.dir>../../../../spring-data-commons/src/main/asciidoc</spring-data-commons-docs.dir>
 		<springdata.commons>3.2.0-SNAPSHOT</springdata.commons>
 	</properties>
 
@@ -725,34 +723,41 @@
 					</execution>
 				</executions>
 			</plugin>
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-resources-plugin</artifactId>
+				<executions>
+					<execution>
+						<goals>
+							<goal>resources</goal>
+						</goals>
+					</execution>
+				</executions>
+			</plugin>
 		</plugins>
 
 	</build>
 
 	<profiles>
 		<profile>
-			<id>distribute</id>
+			<id>antora-process-resources</id>
+			<build>
+				<resources>
+					<resource>
+						<directory>src/main/antora/resources/antora-resources</directory>
+						<filtering>true</filtering>
+					</resource>
+				</resources>
+			</build>
+		</profile>
+
+		<profile>
+			<id>antora</id>
 			<build>
 				<plugins>
 					<plugin>
-						<groupId>org.asciidoctor</groupId>
-						<artifactId>asciidoctor-maven-plugin</artifactId>
-						<version>${asciidoctor-maven-plugin.version}</version>
-						<dependencies>
-							<dependency>
-								<groupId>org.asciidoctor</groupId>
-								<artifactId>asciidoctorj-diagram</artifactId>
-								<version>${asciidoctorj-diagram.version}</version>
-							</dependency>
-						</dependencies>
-						<configuration combine.self="append">
-							<attributes>
-								<spring-data-commons-docs>${spring-data-commons-docs.dir}</spring-data-commons-docs>
-							</attributes>
-							<requires>
-								<require>asciidoctor-diagram</require>
-							</requires>
-						</configuration>
+						<groupId>io.spring.maven.antora</groupId>
+						<artifactId>antora-maven-plugin</artifactId>
 					</plugin>
 				</plugins>
 			</build>

src/main/antora/antora-playbook.yml

@@ -0,0 +1,42 @@
+# 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-neo4j'
+site:
+  title: Spring Data Neo4j
+  url: https://docs.spring.io/spring-data/neo4j/reference/
+content:
+  sources:
+    - url: ./../../..
+      branches: HEAD
+      start_path: src/main/antora
+      worktrees: true
+    - url: https://github.com/spring-projects/spring-data-commons
+      # Refname matching:
+      # https://docs.antora.org/antora/latest/playbook/content-refname-matching/
+      branches: [ main, 3.2.x ]
+      start_path: src/main/antora
+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
+    snapshot: true

src/main/antora/antora.yml

@@ -0,0 +1,12 @@
+name: data-neo4j
+version: true
+title: Spring Data Neo4j
+nav:
+  - modules/ROOT/nav.adoc
+ext:
+  collector:
+    - run:
+        command: ./mvnw validate process-resources -am -Pantora-process-resources
+        local: true
+      scan:
+        dir: target/classes/

src/main/antora/modules/ROOT/examples/config

@@ -0,0 +1 @@
+../../../../java/org/springframework/data/neo4j/config

src/main/antora/modules/ROOT/examples/core

@@ -0,0 +1 @@
+../../../../java/org/springframework/data/neo4j/core

src/main/antora/modules/ROOT/examples/documentation

@@ -0,0 +1 @@
+../../../../../test/java/org/springframework/data/neo4j/documentation

src/main/antora/modules/ROOT/examples/integration

@@ -0,0 +1 @@
+../../../../../test/java/org/springframework/data/neo4j/integration

src/main/antora/modules/ROOT/examples/repository

@@ -0,0 +1 @@
+../../../../java/org/springframework/data/neo4j/repository

src/main/asciidoc/images/bacon-distance.png renamed to src/main/antora/modules/ROOT/images/bacon-distance.png

@@ -0,0 +1,43 @@
+* xref:introduction-and-preface/index.adoc[Preface]
+** xref:introduction-and-preface/preface-neo4j.adoc[]
+** xref:introduction-and-preface/preface-sd.adoc[]
+** xref:introduction-and-preface/preface-sdn.adoc[]
+** xref:introduction-and-preface/building-blocks.adoc[]
+** xref:introduction-and-preface/new-and-noteworthy.adoc[]
+** xref:dependencies.adoc[]
+
+* xref:getting-started.adoc[]
+* xref:object-mapping.adoc[]
+** xref:object-mapping/metadata-based-mapping.adoc[]
+** xref:object-mapping/mapping-ids.adoc[]
+** xref:object-mapping/sdc-object-mapping.adoc[]
+
+* xref:repositories.adoc[]
+** xref:repositories/core-concepts.adoc[]
+** xref:repositories/query-methods.adoc[]
+** xref:repositories/definition.adoc[]
+** xref:repositories/query-methods-details.adoc[]
+** xref:repositories/create-instances.adoc[]
+** xref:repositories/custom-implementations.adoc[]
+** xref:repositories/core-domain-events.adoc[]
+** xref:repositories/core-extensions.adoc[]
+** xref:query-by-example.adoc[]
+** xref:repositories/scrolling.adoc[]
+** xref:repositories/sdn-extension.adoc[]
+** xref:repositories/query-keywords-reference.adoc
+** xref:repositories/query-return-types-reference.adoc
+
+* xref:repositories/projections.adoc[]
+** xref:projections/sdn-projections.adoc[]
+
+* xref:testing.adoc[]
+** xref:testing/testing-without-spring-boot.adoc[]
+** xref:testing/testing-with-spring-boot.adoc[]
+
+* xref:auditing.adoc[]
+
+* xref:faq.adoc[]
+
+* xref:appendix/index.adoc[]
+
+* https://github.com/spring-projects/spring-data-commons/wiki[Wiki]

src/main/asciidoc/images/custom-query.paths.png renamed to src/main/antora/modules/ROOT/images/custom-query.paths.png

@@ -7,7 +7,7 @@ Those come in handy if you cannot express the finder logic via derived query fun
 Because Spring Data Neo4j works heavily record-oriented under the hood, it is important to keep this in mind and not build up a result set with multiple records for the same "root node".
 
 TIP: Please have a look in the FAQ as well to learn about alternative forms of using custom queries from repositories, especially
-how to use custom queries with custom mappings: <<faq.custom-queries-and-custom-mappings>>.
+how to use custom queries with custom mappings: xref:faq.adoc#faq.custom-queries-and-custom-mappings[Custom queries and custom mappings].
 
 [[custom-queries.for-relationships]]
 == Queries with relationships
@@ -59,7 +59,7 @@ There are two ways to achieve this: Database-side or client-side reduction.
 For this the example from above should also contain `Movies` on the `Persons` that get returned with the initial `Movie`.
 
 .Example for 'The Matrix' and 'Keanu Reeves'
-image::movie-graph-deep.png[]
+image::image$movie-graph-deep.png[]
 
 [[custom-queries.for-relationships.long-paths.database]]
 ==== Database-side reduction
@@ -132,17 +132,17 @@ Given are a graph that looks like this:
 
 [[custom-query.paths.g]]
 .graph with outgoing relationships
-image::custom-query.paths.png[]
+image::image$custom-query.paths.png[]
 
 and a domain model as shown in the <<custom-query.paths.dm,mapping>> (Constructors and accessors have been omitted for brevity):
 
 [[custom-query.paths.dm]]
 [source,java,indent=0,tabsize=4]
 .Domain model for a <<custom-query.paths.g>>.
 ----
-include::../../../../src/test/java/org/springframework/data/neo4j/integration/issues/gh2210/SomeEntity.java[tag=custom-query.paths.dm]
+include::example$integration/issues/gh2210/SomeEntity.java[tag=custom-query.paths.dm]
 
-include::../../../../src/test/java/org/springframework/data/neo4j/integration/issues/gh2210/SomeRelation.java[tag=custom-query.paths.dm]
+include::example$integration/issues/gh2210/SomeRelation.java[tag=custom-query.paths.dm]
 ----
 
 As you see, the relationships are only outgoing. Generated finder methods (including `findById`) will always try to match
@@ -177,12 +177,12 @@ populated, linked together and returned.
 == Parameters in custom queries
 
 You do this exactly the same way as in a standard Cypher query issued in the Neo4j Browser or the Cypher-Shell,
-with the `$` syntax (from Neo4j 4.0 on upwards, the old `{foo}` syntax for Cypher parameters has been removed from the database).
+with the `$` syntax (from Neo4j 4.0 on upwards, the old `$\{foo\}` syntax for Cypher parameters has been removed from the database).
 
 [source,java,indent=0]
 .ARepository.java
 ----
-include::../../../../src/test/java/org/springframework/data/neo4j/documentation/repositories/domain_events/ARepository.java[tags=standard-parameter]
+include::example$documentation/repositories/domain_events/ARepository.java[tags=standard-parameter]
 ----
 <.> Here we are referring to the parameter by its name.
 You can also use `$0` etc. instead.
@@ -370,7 +370,7 @@ One way to do this are correlated subqueries (Neo4j 4.1+ required).
 [[custom-queries.spel]]
 == Spring Expression Language in custom queries
 
-{spring-framework-ref}/core.html#expressions[Spring Expression Language (SpEL)] can be used in custom queries inside `:#{}`.
+{springdocsurl}/core/expressions.html[Spring Expression Language (SpEL)] can be used in custom queries inside `:#{}`.
 The colon here refers to a parameter and such an expression should be used where parameters make sense.
 However, when using our <<literal-extension,literal extension>> you can use SpEL expression in places where standard Cypher
 won't allow parameters (such as for labels or relationship types).
@@ -382,16 +382,16 @@ The following example basically defines the same query as above, but uses a `WHE
 [[custom-queries-with-spel-parameter-example]]
 .ARepository.java
 ----
-include::../../../../src/test/java/org/springframework/data/neo4j/documentation/repositories/domain_events/ARepository.java[tags=spel]
+include::example$documentation/repositories/domain_events/ARepository.java[tags=spel]
 ----
 
 The SpEL blocked starts with `:#{` and then refers to the given `String` parameters by name (`#pt1`).
 Don't confuse this with the above Cypher syntax!
-The SpEL expression concatenates both parameters into one single value that is eventually passed on to the <<neo4j-client>>.
+The SpEL expression concatenates both parameters into one single value that is eventually passed on to the xref:appendix/neo4j-client.adoc#neo4j-client[].
 The SpEL block ends with `}`.
 
 SpEL also solves two additional problems. We provide two extensions that allow to pass in a `Sort` object into custom queries.
-Remember <<custom-queries-with-page-and-slice-examples>> from <<faq.custom-queries-with-page-and-slice,custom queries>>?
+Remember xref:faq.adoc#custom-queries-with-page-and-slice-examples[] from xref:faq.adoc#faq.custom-queries-with-page-and-slice[custom queries]?
 With the `orderBy` extension you can pass in a `Pageable` with a dynamic sort to a custom query:
 
 [[custom-queries.spel.source]]

src/main/asciidoc/images/movie-graph-deep.png renamed to src/main/antora/modules/ROOT/images/movie-graph-deep.png

@@ -1,11 +1,9 @@
 [[sdn-appendix]]
 [appendix]
-= Spring Data Neo4j
+= Appendix
 
 :leveloffset: +1
 
-include::conversions.adoc[]
-
 include::neo4j-client.adoc[]
 
 include::query-creation.adoc[]

src/main/antora/modules/ROOT/images/sdn-buildingblocks.png

@@ -93,7 +93,7 @@ spring.neo4j.authentication.password=secret
 
 WARNING: Those new properties might change in the future again when SDN and the driver eventually fully replace the old setup.
 
-And finally, add the new dependency, see <<getting-started>> for both Gradle and Maven.
+And finally, add the new dependency, see xref:getting-started.adoc[Getting started] for both Gradle and Maven.
 
 You're then ready to replace annotations:
 
@@ -125,7 +125,7 @@ You're then ready to replace annotations:
 |No replacement, not needed
 
 |`org.springframework.data.neo4j.annotation.QueryResult`
-|Use <<projections, projections>>; arbitrary result mapping not supported anymore
+|Use xref:repositories/projections.adoc[projections]; arbitrary result mapping not supported anymore
 
 |===
 
@@ -141,7 +141,7 @@ interface and its only implementation `org.springframework.data.neo4j.bookmark.C
 SDN uses bookmarks for all transactions, without configuration.
 You can remove the bean declaration of `CaffeineBookmarkManager` as well as the dependency to `com.github.ben-manes.caffeine:caffeine`.
 
-If you absolutely must, you can disable the automatic bookmark management by following <<faq.bookmarks.noop, these instructions>>.
+If you absolutely must, you can disable the automatic bookmark management by following xref:faq.adoc#faq.bookmarks.noop[these instructions].
 
 [[migrating.autoindex]]
 === Automatic creation of constraints and indexes

src/main/asciidoc/images/springdatagraph.png renamed to src/main/antora/modules/ROOT/images/springdatagraph.png

@@ -16,7 +16,7 @@ The client has the following main goals
 
 SDN relies on all those features and uses them to fulfill its entity mapping features.
 
-Have a look at the <<sdn-building-blocks, SDN building blocks>> for where both the imperative and reactive Neo4 clients are positioned in our stack.
+Have a look at the xref:introduction-and-preface/building-blocks.adoc#sdn-building-blocks[SDN building blocks] for where both the imperative and reactive Neo4 clients are positioned in our stack.
 
 The Neo4j Client comes in two flavors:
 

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

@@ -0,0 +1,2 @@
+[[auditing]]
+include::{commons}@data-commons::page$auditing.adoc[]

src/main/asciidoc/appendix/build.adoc renamed to src/main/antora/modules/ROOT/pages/appendix/build.adoc

@@ -0,0 +1 @@
+include::{commons}@data-commons::page$dependencies.adoc[]