Migrate documentation to Antora.

Closes #2304

.gitignore

@@ -12,3 +12,7 @@ target/
 vf.gf.*
 out/
 _site
+node_modules
+package-lock.json
+package.json
+node

README.adoc

@@ -2,7 +2,7 @@
 
 The goal of the project is to provide a flexible and configurable mechanism for writing simple services that can be exposed over HTTP.
 
-The first exporter implemented is a JPA Repository exporter. This takes your JPA repositories and front-ends them with HTTP, allowing you full CRUD capability over your entities, to include managing associations.
+This takes your Spring Data repositories and front-ends them with HTTP, allowing you full CRUD capability over your entities, to include managing associations.
 
 == Features
 
@@ -15,7 +15,7 @@ The first exporter implemented is a JPA Repository exporter. This takes your JPA
 * https://docs.spring.io/spring-data/rest/docs/current/reference/html/#metadata[Exposes metadata] about the model discovered as ALPS and JSON Schema.
 * Allows to define client specific representations through https://docs.spring.io/spring-data/rest/docs/current/reference/html/#projections-excerpts[projections].
 * Ships the latest release of https://docs.spring.io/spring-data/rest/docs/current/reference/html/#tools.hal-explorer[HAL Explorer] to easily explore HAL and HAL-FORMS based HTTP responses.
-* Currently supports JPA, MongoDB, Neo4j, Solr, Cassandra, Gemfire.
+* Supports JPA, MongoDB, Neo4j, Solr, Cassandra, Gemfire.
 * Allows https://docs.spring.io/spring-data/rest/docs/current/reference/html/#customizing-sdr[advanced customizations] of the default resources exposed.
 
 == Code of Conduct

spring-data-rest-distribution/pom.xml

@@ -19,18 +19,38 @@
 
 	<properties>
 		<project.root>${basedir}/..</project.root>
-		<dist.key>SDREST</dist.key>
+		<antora.playbook>${project.basedir}/../src/main/antora/antora-playbook.yml</antora.playbook>
 	</properties>
 
 	<build>
+		<resources>
+			<resource>
+				<directory>${project.basedir}/../src/main/antora/resources/antora-resources</directory>
+				<filtering>true</filtering>
+			</resource>
+		</resources>
 		<plugins>
 			<plugin>
 				<groupId>org.apache.maven.plugins</groupId>
 				<artifactId>maven-assembly-plugin</artifactId>
 			</plugin>
+
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-resources-plugin</artifactId>
+				<executions>
+					<execution>
+						<goals>
+							<goal>resources</goal>
+						</goals>
+					</execution>
+				</executions>
+
+			</plugin>
+
 			<plugin>
-				<groupId>org.asciidoctor</groupId>
-				<artifactId>asciidoctor-maven-plugin</artifactId>
+				<groupId>io.spring.maven.antora</groupId>
+				<artifactId>antora-maven-plugin</artifactId>
 			</plugin>
 		</plugins>
 	</build>

src/main/antora/antora-playbook.yml

@@ -0,0 +1,37 @@
+# PACKAGES antora@3.2.0-alpha.2 @antora/atlas-extension:1.0.0-alpha.1 @antora/collector-extension@1.0.0-alpha.3 @springio/antora-extensions@1.1.0-alpha.2 @asciidoctor/tabs@1.0.0-alpha.12 @opendevise/antora-release-line-extension@1.0.0-alpha.2
+#
+# 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-rest'
+site:
+  title: Spring Data REST
+  url: https://docs.spring.io/spring-data-rest/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.5/ui-bundle.zip
+    snapshot: true

src/main/antora/antora.yml

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

src/main/antora/modules/ROOT/examples/mongodb

@@ -0,0 +1 @@
+../../../../../../spring-data-rest-tests/spring-data-rest-tests-mongodb/src/main/java/org/springframework/data/rest/tests/mongodb

src/main/antora/modules/ROOT/examples/security

@@ -0,0 +1 @@
+../../../../../../spring-data-rest-tests/spring-data-rest-tests-security/src/test/java/org/springframework/data/rest/tests/security

src/main/antora/modules/ROOT/examples/support

@@ -0,0 +1 @@
+../../../../../../spring-data-rest-webmvc/src/test/java/org/springframework/data/rest/webmvc/support

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

@@ -0,0 +1,30 @@
+* xref:index.adoc[]
+
+* xref:intro.adoc[]
+** xref:introduction/upgrade.adoc[]
+** xref:introduction/getting-started.adoc[]
+** xref:introduction/example-api-usage-with-curl.adoc[]
+** xref:introduction/spring-data-rest-examples.adoc[]
+
+* xref:repository-resources.adoc[]
+** xref:paging-and-sorting.adoc[]
+** xref:projections-excerpts.adoc[]
+
+* xref:representations.adoc[Representations]
+* xref:etags-and-other-conditionals.adoc[Conditional Operations]
+* xref:validation.adoc[]
+* xref:events.adoc[]
+* xref:integration.adoc[]
+* xref:metadata.adoc[]
+* xref:security.adoc[]
+* xref:tools.adoc[]
+
+* xref:customizing-sdr.adoc[]
+** xref:customizing/configuring-the-rest-url-path.adoc[]
+** xref:customizing/adding-sdr-to-spring-mvc-app.adoc[]
+** xref:customizing/overriding-sdr-response-handlers.adoc[]
+** xref:customizing/customizing-json-output.adoc[]
+** xref:customizing/custom-jackson-deserialization.adoc[]
+** xref:customizing/configuring-cors.adoc[]
+
+* https://github.com/spring-projects/spring-data-commons/wiki[Wiki]

src/main/asciidoc/customizing-sdr.adoc → src/main/antora/modules/ROOT/pages/customizing-sdr.adoc

@@ -68,7 +68,7 @@ Notice how `getResourceIdentifier(…)` returns the username to be used by the U
 [[customizing-sdr.repository-exposure]]
 == Customizing repository exposure
 
-By default, all public Spring Data repositories are used to expose HTTP resources as described in <<repository-resources>>.
+By default, all public Spring Data repositories are used to expose HTTP resources as described in xref:repository-resources.adoc[Repository resources].
 Package protected repository interfaces are excluded from this list, as you express its functionality is only visible to the package internally.
 This can be customized by explicitly setting a `RepositoryDetectionStrategy` (usually through the enum `RepositoryDetectionStrategies`) on `RepositoryRestConfiguration`.
 The following values can be configured:
@@ -86,12 +86,12 @@ If you need custom rules to apply, simply implement `RepositoryDetectionStrategy
 [[customizing-sdr.http-methods.default-exposure]]
 === Customizing default exposure
 
-By default, Spring Data REST exposes HTTP resources and methods as described in <<repository-resources>> based on which CRUD methods the repository exposes.
+By default, Spring Data REST exposes HTTP resources and methods as described in xref:repository-resources.adoc[Repository resources] based on which CRUD methods the repository exposes.
 The repositories don't need to extend `CrudRepository` but can also selectively declare methods described in aforementioned section and the resource exposure will follow.
 E.g. if a repository does not expose a `delete(…)` method, an HTTP `DELETE` will not be supported for item resources.
 
 If you need to declare a method for internal use but don't want it to trigger the HTTP method exposure, the repository method can be annotated with `@RestResource(exported = false)`.
-Which methods to annotate like that to remove support for which HTTP method is described in <<repository-resources>>.
+Which methods to annotate like that to remove support for which HTTP method is described in xref:repository-resources.adoc[Repository resources].
 
 Sometimes managing the exposure on the method level is not fine-grained enough.
 E.g. the `save(…)` method is used to back `POST` on collection resources, as well as `PUT` and `PATCH` on item resources.
@@ -110,9 +110,3 @@ config.withItemExposure((metadata, httpMethods) -> httpMethods.disable(HttpMetho
 <2> Disables the support for HTTP `PATCH` on all item resources.
 
 
-include::configuring-the-rest-url-path.adoc[leveloffset=+1]
-include::adding-sdr-to-spring-mvc-app.adoc[leveloffset=+1]
-include::overriding-sdr-response-handlers.adoc[leveloffset=+1]
-include::customizing-json-output.adoc[leveloffset=+1]
-include::custom-jackson-deserialization.adoc[leveloffset=+1]
-include::configuring-cors.adoc[leveloffset=+1]

src/main/asciidoc/etags-and-other-conditionals.adoc → src/main/antora/modules/ROOT/pages/etags-and-other-conditionals.adoc

@@ -1,6 +1,5 @@
 [[conditional]]
 = Conditional Operations with Headers
-:spring-data-rest-root: ../../..
 
 This section shows how Spring Data REST uses standard HTTP headers to enhance performance, conditionalize operations, and contribute to a more sophisticated frontend.
 
@@ -15,7 +14,7 @@ Consider the following example:
 ====
 [source,java,indent=0]
 ----
-include::{spring-data-rest-root}/spring-data-rest-webmvc/src/test/java/org/springframework/data/rest/webmvc/support/ETagUnitTests.java[tag=versioned-sample]
+include::example$support/ETagUnitTests.java[tag=versioned-sample]
 ----
 
 <1> The `@Version` annotation (the JPA one in case you're using Spring Data JPA, the Spring Data `org.springframework.data.annotation.Version` one for all other modules) flags this field as a version marker.
@@ -56,7 +55,7 @@ The https://tools.ietf.org/html/rfc7232#section-3.3[`If-Modified-Since` header]
 ====
 [source,java]
 ----
-include::{spring-data-rest-root}/spring-data-rest-tests/spring-data-rest-tests-mongodb/src/main/java/org/springframework/data/rest/tests/mongodb/Receipt.java[tag=code]
+include::example$mongodb/Receipt.java[tag=code]
 ----
 
 <1> Spring Data Commons's `@LastModifiedDate` annotation allows capturing this information in multiple formats (JodaTime's `DateTime`, legacy Java `Date` and `Calendar`, JDK8 date/time types, and `long`/`Long`).

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

@@ -0,0 +1,27 @@
+[[spring-data-rest-reference-documentation]]
+= Spring Data REST
+:feature-scroll: true
+
+_Spring Data REST exports Spring Data repositories as REST resources through WebMVC.
+It eases development of applications with a consistent programming model backed by Spring Data modules sources._
+
+[horizontal]
+xref:intro.adoc[Introduction] :: Introduction to Spring Data REST and Examples
+xref:repository-resources.adoc[Repository Resources] :: Exporting Repositories as REST Resources
+xref:representations.adoc[Representations] :: Domain Object Representations (Object Mapping)
+xref:etags-and-other-conditionals.adoc[Conditionals] :: Conditional Operations with ETag and other Headers
+xref:validation.adoc[Validation] :: Validator Integration
+xref:events.adoc[Events] :: Listening to REST Events
+xref:integration.adoc[Integration] :: Integration with Spring Data REST components
+xref:metadata.adoc[Metadata] :: ALPS and JSON Schema
+xref:security.adoc[Security] :: Spring Security Integration
+xref:tools.adoc[Tools] :: HAL Explorer
+xref:customizing-sdr.adoc[Customizing] :: Tutorials and Recipes to customize Spring Data REST
+https://github.com/spring-projects/spring-data-commons/wiki[Wiki] :: What's New,
+Upgrade Notes, Supported Versions, additional cross-version information.
+
+Jon Brisbin, Oliver Drotbohm, Greg Turnquist, Jay Bryant
+
+(C) 2008-2023 VMware, Inc.
+
+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.

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

@@ -1,6 +1,5 @@
 [[integration]]
 = Integration
-:spring-data-rest-root: ../../../..
 
 This section details various ways to integrate with Spring Data REST components, whether from a Spring application that is using Spring Data REST or from other means.
 

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

@@ -1,5 +1,6 @@
 [[intro-chapter]]
 = Introduction
+:page-section-summary-toc: 1
 
 REST web services have become the number one means for application integration on the web. In its core, REST defines that a system that consists of resources with which clients interact. These resources are implemented in a hypermedia-driven way. link:{springDocsUrl}/web.html#spring-web[Spring MVC] and link:{springDocsUrl}/web-reactive.html#spring-webflux[Spring WebFlux] each offer a solid foundation to build theses kinds of services. However, implementing even the simplest tenet of REST web services for a multi-domain object system can be quite tedious and result in a lot of boilerplate code.
 

src/main/asciidoc/example-api-usage-with-curl.adoc → src/main/antora/modules/ROOT/pages/introduction/example-api-usage-with-curl.adoc

@@ -1,6 +1,8 @@
 [[example-api-usage-with-curl]]
 [appendix]
+[[using-curl-to-talk-to-spring-data-rest]]
 = Using cURL to talk to Spring Data REST
+:page-section-summary-toc: 1
 
 This appendix contains a list of guides that demonstrate interacting with a Spring Data REST service over cURL:
 

src/main/asciidoc/getting-started.adoc → src/main/antora/modules/ROOT/pages/introduction/getting-started.adoc

@@ -89,9 +89,9 @@ Make sure you also configure Spring Data repositories for the store you use. For
 
 This section covers the basic settings that you can manipulate when you configure a Spring Data REST application, including:
 
-* <<getting-started.setting-repository-detection-strategy>>
-* <<getting-started.changing-base-uri>>
-* <<getting-started.changing-other-properties>>
+* xref:introduction/getting-started.adoc#getting-started.setting-repository-detection-strategy[Setting the Repository Detection Strategy]
+* xref:introduction/getting-started.adoc#getting-started.changing-base-uri[Changing the Base URI]
+* xref:introduction/getting-started.adoc#getting-started.changing-other-properties[Changing Other Spring Data REST Properties]
 
 [[getting-started.setting-repository-detection-strategy]]
 === Setting the Repository Detection Strategy
@@ -209,4 +209,4 @@ You can run your application as either a Spring Boot app (with the links shown e
 
 NOTE: In general, Spring Data REST does not add functionality to a given data store. This means that, by definition, it should work with any Spring Data project that supports the repository programming model. The data stores listed above are the ones for which we have written integration tests to verify that Spring Data REST works with them.
 
-From this point, you can  <<customizing-sdr,customize Spring Data REST>> with various options.
+From this point, you can  xref:customizing-sdr.adoc[customize Spring Data REST] with various options.

src/main/asciidoc/spring-data-rest-examples.adoc → src/main/antora/modules/ROOT/pages/introduction/spring-data-rest-examples.adoc

@@ -1,5 +1,6 @@
 [[spring-data-examples]]
 [appendix]
+[[spring-data-rest-example-projects]]
 = Spring Data REST example projects
 
 This appendix contains a list of Spring Data REST sample applications. The exact version of each example is not guaranteed to match the version of this reference manual.
@@ -14,7 +15,7 @@ https://github.com/spring-projects/spring-data-examples/tree/master/rest/multi-s
 [[spring-data-examples.projections]]
 == Projections
 
-https://github.com/spring-projects/spring-data-examples/tree/master/rest/projections[This example] contains more detailed code you can use to explore <<projections-excerpts,projections>>.
+https://github.com/spring-projects/spring-data-examples/tree/master/rest/projections[This example] contains more detailed code you can use to explore xref:projections-excerpts.adoc[projections].
 
 [[spring-data-examples.spring-security]]
 == Spring Data REST with Spring Security

src/main/antora/modules/ROOT/pages/introduction/upgrade.adoc

@@ -0,0 +1,8 @@
+[[new-features]]
+[[upgrading]]
+= Upgrading Spring Data
+
+Instructions for how to upgrade from earlier versions of Spring Data are provided on the project https://github.com/spring-projects/spring-data-commons/wiki[wiki].
+Follow the links in the https://github.com/spring-projects/spring-data-commons/wiki#release-notes[release notes section] to find the version that you want to upgrade to.
+
+Upgrading instructions are always the first item in the release notes. If you are more than one release behind, please make sure that you also review the release notes of the versions that you jumped.

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

@@ -178,7 +178,7 @@ shown in the preceding table.
 === ALPS with Projections
 
 If you define any projections, they are also listed in the ALPS metadata. Assuming we also defined `inlineAddress` and `noAddresses`, they
-would appear inside the relevant operations. (See "`<<projections-excerpts.projections>>`" for the definitions and discussion of these two projections.) That is *GET* would appear in the operations for the whole collection, and *GET* would appear in the operations for a single resource. The following example shows
+would appear inside the relevant operations. (See "`xref:projections-excerpts.adoc#projections-excerpts.projections[Projections]`" for the definitions and discussion of these two projections.) That is *GET* would appear in the operations for the whole collection, and *GET* would appear in the operations for a single resource. The following example shows
 the alternate version of the `get-persons` subsection:
 
 ====
@@ -319,7 +319,7 @@ https://json-schema.org/[JSON Schema] is another form of metadata supported by S
 * Clear, human- and machine-readable documentation
 * Complete structural validation, useful for automated testing and validating client-submitted data
 
-As shown in the <<metadata.alps,previous section>>, you can reach this data by navigating from the root URI to the `profile` link.
+As shown in the xref:metadata.adoc#metadata.alps[previous section], you can reach this data by navigating from the root URI to the `profile` link.
 
 ====
 [source,javascript]
@@ -417,7 +417,7 @@ You can also find a `profile` link in the collection of `_links` when you examin
 <2> It has a *profile* link to the same URI for metadata.
 ====
 
-Again, the `profile` link serves <<metadata.alps,ALPS>> by default. If you supply it with an https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1[`Accept` header] of `application/schema+json`, it renders the JSON Schema representation.
+Again, the `profile` link serves xref:metadata.adoc#metadata.alps[ALPS] by default. If you supply it with an https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1[`Accept` header] of `application/schema+json`, it renders the JSON Schema representation.
 
 //= JSON Patch
 

src/main/asciidoc/projections-excerpts.adoc → src/main/antora/modules/ROOT/pages/projections-excerpts.adoc

@@ -142,7 +142,7 @@ NOTE: The value supplied to the `projection` query parameter is the same as that
 
 You can have multiple projections.
 
-NOTE: See <<spring-data-examples.projections>> to see an example project. We encourage you to experiment with it.
+NOTE: See xref:introduction/spring-data-rest-examples.adoc#spring-data-examples.projections[Projections] to see an example project. We encourage you to experiment with it.
 
 Spring Data REST finds projection definitions as follows:
 
@@ -154,7 +154,7 @@ In either case, the projection interface must have the `@Projection` annotation.
 [[projections-excerpts.finding-projections]]
 === Finding Existing Projections
 
-Spring Data REST exposes <<metadata.alps>> documents, a micro metadata format. To view the ALPS metadata, follow the `profile` link exposed by the root resource. If you navigate down to the ALPS document for `Person` resources (which would be `/alps/persons`), you can find many details about `Person` resources. Projections are listed, along with the details about the `GET` REST transition, in blocks similar to the following example:
+Spring Data REST exposes xref:metadata.adoc#metadata.alps[Application-Level Profile Semantics (ALPS)] documents, a micro metadata format. To view the ALPS metadata, follow the `profile` link exposed by the root resource. If you navigate down to the ALPS document for `Person` resources (which would be `/alps/persons`), you can find many details about `Person` resources. Projections are listed, along with the details about the `GET` REST transition, in blocks similar to the following example:
 
 ====
 [source,javascript]