Migrate documentation site to Antora.

Closes #2685

Author: mp911de

.gitignore

@@ -26,3 +26,9 @@ target
 /zap.env
 /localdocker.env
 .localdocker-env
+
+build/
+node_modules
+node
+package.json
+package-lock.json

README.adoc

@@ -137,7 +137,7 @@ If you want to raise an issue, please follow the recommendations below:
 
 * Before you log a bug, please search the
 https://github.com/spring-projects/spring-data-elasticsearch/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-elasticsearch/issues/new[create a new issue].
+* If the issue doesn't already exist, https://github.com/spring-projects/spring-data-elasticsearch/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 Elasticsearch that you are using and JVM version.
 * 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.
@@ -168,10 +168,10 @@ Building the documentation builds also the project without running tests.
 
 [source,bash]
 ----
- $ ./mvnw clean install -Pdistribute
+ $ ./mvnw clean install -Pantora
 ----
 
-The generated documentation is available from `target/site/reference/html/index.html`.
+The generated documentation is available from `target/antora/site/index.html`.
 
 == Examples
 

pom.xml

@@ -409,10 +409,6 @@
 				<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>
 
@@ -463,6 +459,30 @@
 				</plugins>
 			</build>
 		</profile>
+
+		<profile>
+			<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>io.spring.maven.antora</groupId>
+						<artifactId>antora-maven-plugin</artifactId>
+					</plugin>
+				</plugins>
+			</build>
+		</profile>
 	</profiles>
 
 	<repositories>

src/main/antora/antora-playbook.yml

@@ -0,0 +1,42 @@
+# 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-elasticsearch'
+site:
+  title: Spring Data Elasticsearch
+  url: https://docs.spring.io/spring-data-elasticsearch/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-elasticsearch
+version: true
+title: Spring Data Elasticsearch
+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/nav.adoc

@@ -0,0 +1,42 @@
+* xref:index.adoc[Overview]
+** xref:commons/upgrade.adoc[]
+** xref:migration-guides.adoc[]
+*** xref:migration-guides/migration-guide-3.2-4.0.adoc[]
+*** xref:migration-guides/migration-guide-4.0-4.1.adoc[]
+*** xref:migration-guides/migration-guide-4.1-4.2.adoc[]
+*** xref:migration-guides/migration-guide-4.2-4.3.adoc[]
+*** xref:migration-guides/migration-guide-4.3-4.4.adoc[]
+*** xref:migration-guides/migration-guide-4.4-5.0.adoc[]
+*** xref:migration-guides/migration-guide-5.0-5.1.adoc[]
+*** xref:migration-guides/migration-guide-5.1-5.2.adoc[]
+
+
+* xref:elasticsearch.adoc[]
+** xref:elasticsearch/clients.adoc[]
+** xref:elasticsearch/object-mapping.adoc[]
+** xref:elasticsearch/template.adoc[]
+** xref:elasticsearch/reactive-template.adoc[]
+** xref:elasticsearch/entity-callbacks.adoc[]
+** xref:elasticsearch/auditing.adoc[]
+** xref:elasticsearch/join-types.adoc[]
+** xref:elasticsearch/routing.adoc[]
+** xref:elasticsearch/misc.adoc[]
+** xref:elasticsearch/scripted-and-runtime-fields.adoc[]
+
+* xref:repositories.adoc[]
+** xref:repositories/core-concepts.adoc[]
+** xref:repositories/definition.adoc[]
+** xref:elasticsearch/repositories/elasticsearch-repositories.adoc[]
+** xref:elasticsearch/repositories/reactive-elasticsearch-repositories.adoc[]
+** xref:repositories/create-instances.adoc[]
+** xref:repositories/query-methods-details.adoc[]
+** xref:elasticsearch/repositories/elasticsearch-repository-queries.adoc[]
+** xref:repositories/projections.adoc[]
+** xref:repositories/custom-implementations.adoc[]
+** xref:repositories/core-domain-events.adoc[]
+** xref:repositories/null-handling.adoc[]
+** xref:elasticsearch/repositories/cdi-integration.adoc[]
+** xref:repositories/query-keywords-reference.adoc[]
+** xref:repositories/query-return-types-reference.adoc[]
+
+* https://github.com/spring-projects/spring-data-commons/wiki[Wiki]

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

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

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

@@ -0,0 +1,16 @@
+[[elasticsearch.core]]
+= Elasticsearch Support
+:page-section-summary-toc: 1
+
+Spring Data support for Elasticsearch contains a wide range of features:
+
+* Spring configuration support for various xref:elasticsearch/clients.adoc[Elasticsearch clients].
+* The xref:elasticsearch/template.adoc[`ElasticsearchTemplate` and `ReactiveElasticsearchTemplate`] helper classes that provide object mapping between ES index operations and POJOs.
+* xref:elasticsearch/template.adoc#exception-translation[Exception translation] into Spring's portable {springDocsUrl}data-access.html#dao-exceptions[Data Access Exception Hierarchy].
+* Feature rich xref:elasticsearch/object-mapping.adoc[object mapping] integrated with _Spring's_ {springDocsUrl}core.html#core-convert[Conversion Service].
+* xref:elasticsearch/object-mapping.adoc#elasticsearch.mapping.meta-model.annotations[Annotation-based mapping] metadata that is extensible to support other metadata formats.
+* Java-based xref:elasticsearch/template.adoc#cassandra.template.query[query, criteria, and update DSLs].
+* Automatic implementation of xref:repositories.adoc[imperative and reactive `Repository` interfaces] including support for xref:repositories/custom-implementations.adoc[custom query methods].
+
+For most data-oriented tasks, you can use the `[Reactive]ElasticsearchTemplate` or the `Repository` support, both of which use the rich object-mapping functionality.
+Spring Data Elasticsearch uses consistent naming conventions on objects in various APIs to those found in the DataStax Java Driver so that they are familiar and so that you can map your existing knowledge onto the Spring APIs.

src/main/asciidoc/reference/elasticsearch-auditing.adoc renamed to src/main/antora/modules/ROOT/pages/elasticsearch/auditing.adoc

@@ -1,8 +1,8 @@
 [[elasticsearch.auditing]]
-== Elasticsearch Auditing
+= Elasticsearch Auditing
 
 [[elasticsearch.auditing.preparing]]
-=== Preparing entities
+== Preparing entities
 
 In order for the auditing code to be able to decide whether an entity instance is new, the entity must implement the `Persistable<ID>` interface which is defined as follows:
 
@@ -56,7 +56,7 @@ public class Person implements Persistable<Long> {
 <.> an object is new if it either has no `id` or none of fields containing creation attributes are set.
 
 [[elasticsearch.auditing.activating]]
-=== Activating auditing
+== Activating auditing
 
 After the entities have been set up and providing the `AuditorAware` - or `ReactiveAuditorAware` - the Auditing must be activated by setting the `@EnableElasticsearchAuditing` on a configuration class:
 

src/main/asciidoc/reference/elasticsearch-clients.adoc renamed to src/main/antora/modules/ROOT/pages/elasticsearch/clients.adoc

@@ -3,10 +3,8 @@
 
 This chapter illustrates configuration and usage of supported Elasticsearch client implementations.
 
-Spring Data Elasticsearch operates upon an Elasticsearch client (provided by Elasticsearch client libraries) that is 
-connected to a single Elasticsearch node or a cluster. 
-Although the Elasticsearch Client can be used directly to work with the cluster, applications using Spring Data 
-Elasticsearch normally use the higher level abstractions of <<elasticsearch.operations>> and <<elasticsearch.repositories>>.
+Spring Data Elasticsearch operates upon an Elasticsearch client (provided by Elasticsearch client libraries) that is connected to a single Elasticsearch node or a cluster.
+Although the Elasticsearch Client can be used directly to work with the cluster, applications using Spring Data Elasticsearch normally use the higher level abstractions of xref:elasticsearch/template.adoc[Elasticsearch Operations] and xref:elasticsearch/repositories/elasticsearch-repositories.adoc[Elasticsearch Repositories].
 
 [[elasticsearch.clients.restclient]]
 == Imperative Rest Client
@@ -23,13 +21,14 @@ public class MyClientConfig extends ElasticsearchConfiguration {
 
 	@Override
 	public ClientConfiguration clientConfiguration() {
-		return ClientConfiguration.builder()           <.> 
-			.connectedTo("localhost:9200") 
+		return ClientConfiguration.builder()           <.>
+			.connectedTo("localhost:9200")
 			.build();
 	}
 }
 ----
-<.> for a detailed description of the builder methods see <<elasticsearch.clients.configuration>>
+
+<.> for a detailed description of the builder methods see xref:elasticsearch/clients.adoc#elasticsearch.clients.configuration[Client Configuration]
 ====
 
 The `ElasticsearchConfiguration` class allows further configuration by overriding for example the `jsonpMapper()` or `transportOptions()` methods.
@@ -43,14 +42,14 @@ The following beans can then be injected in other Spring components:
 import org.springframework.beans.factory.annotation.Autowired;@Autowired
 ElasticsearchOperations operations;      <.>
 
-@Autowired 
+@Autowired
 ElasticsearchClient elasticsearchClient; <.>
 
 @Autowired
 RestClient restClient;                   <.>
 
 @Autowired
-JsonpMapper jsonpMapper;                 <.> 
+JsonpMapper jsonpMapper;                 <.>
 ----
 
 <.> an implementation of `ElasticsearchOperations`
@@ -78,12 +77,13 @@ public class MyClientConfig extends ReactiveElasticsearchConfiguration {
 	@Override
 	public ClientConfiguration clientConfiguration() {
 		return ClientConfiguration.builder()           <.>
-			.connectedTo("localhost:9200") 
+			.connectedTo("localhost:9200")
 			.build();
 	}
 }
 ----
-<.> for a detailed description of the builder methods see <<elasticsearch.clients.configuration>>
+
+<.> for a detailed description of the builder methods see xref:elasticsearch/clients.adoc#elasticsearch.clients.configuration[Client Configuration]
 ====
 
 The `ReactiveElasticsearchConfiguration` class allows further configuration by overriding for example the `jsonpMapper()` or `transportOptions()` methods.
@@ -96,14 +96,14 @@ The following beans can then be injected in other Spring components:
 @Autowired
 ReactiveElasticsearchOperations operations;      <.>
 
-@Autowired 
+@Autowired
 ReactiveElasticsearchClient elasticsearchClient; <.>
 
 @Autowired
 RestClient restClient;                           <.>
 
 @Autowired
-JsonpMapper jsonpMapper;                         <.> 
+JsonpMapper jsonpMapper;                         <.>
 ----
 
 the following can be injected:
@@ -161,16 +161,15 @@ ClientConfiguration clientConfiguration = ClientConfiguration.builder()
 
 <.> Define default headers, if they need to be customized
 <.> Use the builder to provide cluster addresses, set default `HttpHeaders` or enable SSL.
-<.> Optionally enable SSL. There exist overloads of this function that can take a `SSLContext` or as an alternative the fingerprint of the certificate as it is output by Elasticsearch 8 on startup.
+<.> Optionally enable SSL.There exist overloads of this function that can take a `SSLContext` or as an alternative the fingerprint of the certificate as it is output by Elasticsearch 8 on startup.
 <.> Optionally set a proxy.
 <.> Optionally set a path prefix, mostly used when different clusters a behind some reverse proxy.
 <.> Set the connection timeout.
 <.> Set the socket timeout.
 <.> Optionally set headers.
 <.> Add basic authentication.
 <.> A `Supplier<HttpHeaders>` function can be specified which is called every time before a request is sent to Elasticsearch - here, as an example, the current time is written in a header.
-<.> a function to configure the created client (see <<elasticsearch.clients.configuration.callbacks>>), can be added 
-multiple times.
+<.> a function to configure the created client (see xref:elasticsearch/clients.adoc#elasticsearch.clients.configuration.callbacks[Client configuration callbacks]), can be added multiple times.
 ====
 
 IMPORTANT: Adding a Header supplier as shown in above example allows to inject headers that may change over the time, like authentication JWT tokens.
@@ -179,8 +178,8 @@ If this is used in the reactive setup, the supplier function *must not* block!
 [[elasticsearch.clients.configuration.callbacks]]
 === Client configuration callbacks
 
-The `ClientConfiguration` class offers the most common parameters to configure the client. In the case this is not 
-enough, the user can add callback functions by using the `withClientConfigurer(ClientConfigurationCallback<?>)` method.
+The `ClientConfiguration` class offers the most common parameters to configure the client.
+In the case this is not enough, the user can add callback functions by using the `withClientConfigurer(ClientConfigurationCallback<?>)` method.
 
 The following callbacks are provided:
 
@@ -222,9 +221,8 @@ ClientConfiguration.builder()
 [[elasticsearch.clients.logging]]
 == Client Logging
 
-To see what is actually sent to and received from the server `Request` / `Response` logging on the transport level 
-needs to be turned on as outlined in the snippet below. This can be enabled in the Elasticsearch client by setting 
-the level of the `tracer` package to "trace" (see 
+To see what is actually sent to and received from the server `Request` / `Response` logging on the transport level needs to be turned on as outlined in the snippet below.
+This can be enabled in the Elasticsearch client by setting the level of the `tracer` package to "trace" (see
 https://www.elastic.co/guide/en/elasticsearch/client/java-api-client/current/java-rest-low-usage-logging.html)
 
 .Enable transport layer logging

src/main/asciidoc/reference/elasticsearch-new.adoc renamed to src/main/antora/modules/ROOT/pages/elasticsearch/elasticsearch-new.adoc

@@ -66,7 +66,7 @@
 * Upgrade to Elasticsearch 7.6.2.
 * Deprecation of `TransportClient` usage.
 * Implements most of the mapping-types available for the index mappings.
-* Removal of the Jackson `ObjectMapper`, now using the <<elasticsearch.mapping.meta-model,MappingElasticsearchConverter>>
+* Removal of the Jackson `ObjectMapper`, now using the xref:elasticsearch/object-mapping.adoc#elasticsearch.mapping.meta-model[MappingElasticsearchConverter]
 * Cleanup of the API in the `*Operations` interfaces, grouping and renaming methods so that they match the Elasticsearch API, deprecating the old methods, aligning with other Spring Data modules.
 * Introduction of `SearchHit<T>` class to represent a found document together with the relevant result metadata for this document (i.e. _sortValues_).
 * Introduction of the `SearchHits<T>` class to represent a whole search result together with the metadata for the complete search result (i.e. _max_score_).
@@ -80,7 +80,7 @@
 
 * Secured Elasticsearch cluster support with Basic Authentication and SSL transport.
 * Upgrade to Elasticsearch 6.8.1.
-* Reactive programming support with <<elasticsearch.reactive.operations>> and <<elasticsearch.reactive.repositories>>.
-* Introduction of the <<elasticsearch.mapping.meta-model,ElasticsearchEntityMapper>> as an alternative to the Jackson `ObjectMapper`.
+* Reactive programming support with xref:elasticsearch/repositories/reactive-elasticsearch-repositories.adoc[Reactive Elasticsearch Repositories] and xref:.
+* Introduction of the xref:elasticsearch/object-mapping.adoc#elasticsearch.mapping.meta-model[ElasticsearchEntityMapper] as an alternative to the Jackson `ObjectMapper`.
 * Field name customization in `@Field`.
 * Support for Delete by Query.

src/main/asciidoc/reference/elasticsearch-entity-callbacks.adoc renamed to src/main/antora/modules/ROOT/pages/elasticsearch/entity-callbacks.adoc

@@ -1,5 +1,7 @@
+include::{commons}@data-commons::page$entity-callbacks.adoc[]
+
 [[elasticsearch.entity-callbacks]]
-= Elasticsearch EntityCallbacks
+== Store specific EntityCallbacks
 
 Spring Data Elasticsearch uses the `EntityCallback` API internally for its auditing support and reacts on the following callbacks:
 

src/main/asciidoc/reference/elasticsearch-join-types.adoc renamed to src/main/antora/modules/ROOT/pages/elasticsearch/join-types.adoc

@@ -112,7 +112,7 @@ public class Statement {
     }
 }
 ----
-<.> for routing related info see <<elasticsearch.routing>>
+<.> for routing related info see xref:elasticsearch/routing.adoc[Routing values]
 <.> a question can have answers and comments
 <.> an answer can have votes
 <.> the `JoinField` property is used to combine the name (_question_, _answer_, _comment_ or _vote_) of the relation with the parent id.
@@ -208,13 +208,13 @@ void init() {
 <2> the first answer to the question
 <3> the second answer
 <4> a comment to the question
-<5> a vote for the first answer, this needs to have the routing set to the weather document, see <<elasticsearch.routing>>.
+<5> a vote for the first answer, this needs to have the routing set to the weather document, see xref:elasticsearch/routing.adoc[Routing values].
 ====
 
 [[elasticsearch.jointype.retrieving]]
 ==  Retrieving data
 
-Currently native queries must be used to query the data, so there is no support from standard repository methods. <<repositories.custom-implementations>> can be used instead.
+Currently native queries must be used to query the data, so there is no support from standard repository methods. xref:repositories/custom-implementations.adoc[] can be used instead.
 
 The following code shows as an example how to retrieve all entries that have a _vote_ (which must be _answers_, because only answers can have a vote) using an `ElasticsearchOperations` instance: