Migrate documentation site to Antora.

Closes #2703

Author: mp911de

.gitignore

@@ -16,3 +16,8 @@ out
 work
 *.rdb
 *.aof
+build/
+node_modules
+node
+package.json
+package-lock.json

README.adoc

@@ -97,10 +97,10 @@ If you'd rather like the latest snapshots of the upcoming major version, use our
 Having trouble with Spring Data? We’d love to help!
 
 * Check the
-https://docs.spring.io/spring-data/redis/docs/current/reference/html/[reference documentation], and https://docs.spring.io/spring-data/redis/docs/current/api/[Javadocs].
+https://docs.spring.io/spring-data/redis/docs/reference/[reference documentation], and https://docs.spring.io/spring-data/redis/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/redis/docs/current/changelog.txt[changelog] for "`new and noteworthy`" features.
+* If you are upgrading, check out the https://github.com/spring-projects/spring-data-commons/wiki#release-notes[Release notes] for "`new and noteworthy`" features.
 * Ask a question - we monitor https://stackoverflow.com[stackoverflow.com] for questions tagged with https://stackoverflow.com/tags/spring-data[`spring-data-redis`].
 You can also chat with the community on https://gitter.im/spring-projects/spring-data[Gitter].
 * Report bugs with Spring Data Redis at https://github.com/spring-projects/spring-data-redis/issues/new[github.com/spring-projects/spring-data-redis].
@@ -136,10 +136,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`.
 
 == Guides
 

pom.xml

@@ -19,6 +19,7 @@
 
 	<properties>
 		<springdata.keyvalue>3.2.0-SNAPSHOT</springdata.keyvalue>
+		<springdata.commons>3.2.0-SNAPSHOT</springdata.commons>
 		<awaitility>4.0.2</awaitility>
 		<beanutils>1.9.4</beanutils>
 		<xstream>1.4.20</xstream>
@@ -374,6 +375,28 @@
 				</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 [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-redis'
+site:
+  title: Spring Data Redis
+  url: https://docs.spring.io/spring-data-redis/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-redis
+version: true
+title: Spring Data Redis
+nav:
+  - modules/ROOT/nav.adoc
+ext:
+  collector:
+    - run:
+        command: ./mvnw validate process-resources -Pantora-process-resources
+        local: true
+      scan:
+        dir: target/classes/

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

@@ -0,0 +1 @@
+../../../../../test/java/org/springframework/data/redis/examples

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

@@ -0,0 +1,47 @@
+* xref:index.adoc[Overview]
+** xref:commons/upgrade.adoc[]
+** xref:upgrading.adoc[]
+
+
+* xref:redis.adoc[]
+** xref:redis/getting-started.adoc[]
+** xref:redis/drivers.adoc[]
+** xref:redis/connection-modes.adoc[]
+** xref:redis/template.adoc[RedisTemplate]
+** xref:redis/cluster.adoc[]
+** xref:redis/hash-mappers.adoc[]
+** xref:redis/pubsub.adoc[]
+** xref:redis/redis-streams.adoc[]
+** xref:redis/redis-cache.adoc[]
+** xref:redis/scripting.adoc[]
+** xref:redis/transactions.adoc[]
+** xref:redis/pipelining.adoc[]
+** xref:redis/support-classes.adoc[]
+
+* xref:repositories.adoc[]
+** xref:repositories/core-concepts.adoc[]
+** xref:repositories/definition.adoc[]
+** xref:repositories/create-instances.adoc[]
+** xref:redis/redis-repositories/usage.adoc[]
+** xref:repositories/object-mapping.adoc[]
+** xref:redis/redis-repositories/mapping.adoc[]
+** xref:redis/redis-repositories/keyspaces.adoc[]
+** xref:redis/redis-repositories/indexes.adoc[]
+** xref:redis/redis-repositories/expirations.adoc[]
+** xref:redis/redis-repositories/queries.adoc[]
+** xref:redis/redis-repositories/query-by-example.adoc[]
+** xref:redis/redis-repositories/cluster.adoc[]
+** xref:redis/redis-repositories/anatomy.adoc[]
+** xref:repositories/projections.adoc[]
+** xref:repositories/custom-implementations.adoc[]
+** xref:repositories/core-domain-events.adoc[]
+** xref:repositories/null-handling.adoc[]
+** xref:redis/redis-repositories/cdi-integration.adoc[]
+** xref:repositories/query-keywords-reference.adoc[]
+** xref:repositories/query-return-types-reference.adoc[]
+
+* xref:observability.adoc[]
+
+* xref:appendix.adoc[]
+
+* https://github.com/spring-projects/spring-data-commons/wiki[Wiki]

src/main/asciidoc/appendix/appendix-command-reference.adoc renamed to src/main/antora/modules/ROOT/pages/appendix.adoc

@@ -1,7 +1,12 @@
-[[appendix:command-reference]]
-[appendix]
-= Command Reference
+[[appendix]]
+= Appendix
 
+[[schema]]
+== Schema
+
+link:https://www.springframework.org/schema/redis/spring-redis-1.0.xsd[Spring Data Redis Schema (redis-namespace)]
+
+[[supported-commands]]
 == Supported Commands
 .Redis commands supported by `RedisTemplate`
 [width="50%",cols="<2,^1",options="header"]

src/main/asciidoc/reference/upgrade.adoc renamed to src/main/antora/modules/ROOT/pages/commons/upgrade.adoc

@@ -1,8 +1,6 @@
-include::../{spring-data-commons-docs}/upgrade.adoc[]
-
-== What to Read Next
+include::{commons}@data-commons::page$upgrade.adoc[]
 
 Once you’ve decided to upgrade your application, you can find detailed information regarding specific features in the rest of the document.
-You can find <<redis.upgrading,migration guides>> specific to major version migrations at the end of this document.
+You can find xref:upgrading.adoc#redis.upgrading[migration guides] specific to major version migrations at the end of this document.
 
 Spring Data's documentation is specific to that version, so any information that you find in here will contain the most up-to-date changes that are in that version.

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

@@ -0,0 +1,20 @@
+[[spring-data-redis-reference-documentation]]
+= Spring Data Redis
+:revnumber: {version}
+:revdate: {localdate}
+:feature-scroll: true
+
+_Spring Data Redis provides Redis connectivity and repository support for the Redis database.
+It eases development of applications with a consistent programming model that need to access Redis data sources._
+
+[horizontal]
+xref:redis.adoc[Redis] :: Redis support and connectivity
+xref:repositories.adoc[Repositories] :: Redis Repositories
+xref:observability.adoc[Observability] :: Observability Integration
+https://github.com/spring-projects/spring-data-commons/wiki[Wiki] :: What's New, Upgrade Notes, Supported Versions, additional cross-version information.
+
+Costin Leau, Jennifer Hickey, Christoph Strobl, Thomas Darimont, Mark Paluch, 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/antora/modules/ROOT/pages/observability.adoc

@@ -0,0 +1,107 @@
+[[redis.observability]]
+= Observability
+
+Getting insights from an application component about its operations, timing and relation to application code is crucial to understand latency.
+Spring Data Redis ships with a Micrometer integration through the Lettuce driver to collect observations during Redis interaction.
+Once the integration is set up, Micrometer will create meters and spans (for distributed tracing) for each Redis command.
+
+To enable the integration, apply the following configuration to `LettuceClientConfiguration`:
+
+[source,java]
+----
+@Configuration
+class ObservabilityConfiguration {
+
+  @Bean
+  public ClientResources clientResources(ObservationRegistry observationRegistry) {
+
+    return ClientResources.builder()
+              .tracing(new MicrometerTracingAdapter(observationRegistry, "my-redis-cache"))
+              .build();
+  }
+
+  @Bean
+  public LettuceConnectionFactory lettuceConnectionFactory(ClientResources clientResources) {
+
+    LettuceClientConfiguration clientConfig = LettuceClientConfiguration.builder()
+                                                .clientResources(clientResources).build();
+    RedisConfiguration redisConfiguration = …;
+    return new LettuceConnectionFactory(redisConfiguration, clientConfig);
+  }
+}
+----
+
+See also https://opentelemetry.io/docs/reference/specification/trace/semantic_conventions/database/#redis[OpenTelemetry Semantic Conventions] for further reference.
+
+[[observability-metrics]]
+== Observability - Metrics
+
+Below you can find a list of all metrics declared by this project.
+
+[[observability-metrics-redis-command-observation]]
+== Redis Command Observation
+
+____
+Timer created around a Redis command execution.
+____
+
+**Metric name** `spring.data.redis`. **Type** `timer` and **base unit** `seconds`.
+
+Fully qualified name of the enclosing class `org.springframework.data.redis.connection.lettuce.observability.RedisObservation`.
+
+
+
+.Low cardinality Keys
+[cols="a,a"]
+|===
+|Name | Description
+|`db.operation`|Redis command value.
+|`db.redis.database_index`|Redis database index.
+|`db.system`|Database system.
+|`db.user`|Redis user.
+|`net.peer.name`|Name of the database host.
+|`net.peer.port`|Logical remote port number.
+|`net.sock.peer.addr`|Mongo peer address.
+|`net.sock.peer.port`|Mongo peer port.
+|`net.transport`|Network transport.
+|===
+
+.High cardinality Keys
+[cols="a,a"]
+|===
+|Name | Description
+|`db.statement`|Redis statement.
+|`spring.data.redis.command.error`|Redis error response.
+|===
+
+[[observability-spans]]
+== Observability - Spans
+
+Below you can find a list of all spans declared by this project.
+
+[[observability-spans-redis-command-observation]]
+== Redis Command Observation Span
+
+> Timer created around a Redis command execution.
+
+**Span name** `spring.data.redis`.
+
+Fully qualified name of the enclosing class `org.springframework.data.redis.connection.lettuce.observability.RedisObservation`.
+
+
+
+.Tag Keys
+|===
+|Name | Description
+|`db.operation`|Redis command value.
+|`db.redis.database_index`|Redis database index.
+|`db.statement`|Redis statement.
+|`db.system`|Database system.
+|`db.user`|Redis user.
+|`net.peer.name`|Name of the database host.
+|`net.peer.port`|Logical remote port number.
+|`net.sock.peer.addr`|Mongo peer address.
+|`net.sock.peer.port`|Mongo peer port.
+|`net.transport`|Network transport.
+|`spring.data.redis.command.error`|Redis error response.
+|===

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

@@ -11,14 +11,14 @@ This section provides an easy-to-follow guide for getting started with the Sprin
 == Learning Spring
 
 Spring Data uses Spring framework's
-{spring-framework-reference}/core.html[core] functionality, including:
+{spring-framework-docs}/core.html[core] functionality, including:
 
 
-* {spring-framework-reference}/core.html#beans[IoC] container
-* {spring-framework-reference}/core.html#validation[type conversion system]
-* {spring-framework-reference}/core.html#expressions[expression language]
-* {spring-framework-reference}/integration.html#jmx[JMX integration]
-* {spring-framework-reference}/data-access.html#dao-exceptions[DAO exception hierarchy].
+* {spring-framework-docs}/core.html#beans[IoC] container
+* {spring-framework-docs}/core.html#validation[type conversion system]
+* {spring-framework-docs}/core.html#expressions[expression language]
+* {spring-framework-docs}/integration.html#jmx[JMX integration]
+* {spring-framework-docs}/data-access.html#dao-exceptions[DAO exception hierarchy].
 
 While you need not know the Spring APIs, understanding the concepts behind them is important.
 At a minimum, the idea behind Inversion of Control (IoC) should be familiar, and you should be familiar with whatever IoC container you choose to use.

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

@@ -0,0 +1,43 @@
+[[redis]]
+= Redis
+:page-section-summary-toc: 1
+
+One of the key-value stores supported by Spring Data is https://redis.io[Redis].
+To quote the Redis project home page:
+
+[quote]
+Redis is an advanced key-value store.
+It is similar to memcached but the dataset is not volatile, and values can be strings, exactly like in memcached, but also lists, sets, and ordered sets.
+All this data types can be manipulated with atomic operations to push/pop elements, add/remove elements, perform server side union, intersection, difference between sets, and so forth.
+Redis supports different kind of sorting abilities.
+
+Spring Data Redis provides easy configuration and access to Redis from Spring applications.
+It offers both low-level and high-level abstractions for interacting with the store, freeing the user from infrastructural concerns.
+
+Spring Data support for Redis contains a wide range of features:
+
+* xref:redis/template.adoc[`RedisTemplate` and `ReactiveRedisTemplate` helper class] that increases productivity when performing common Redis operations.
+Includes integrated serialization between objects and values.
+* Exception translation into Spring's portable Data Access Exception hierarchy.
+* Automatic implementation of xref:repositories.adoc[Repository interfaces], including support for custom query methods.
+* Feature-rich xref:redis/redis-repositories/mapping.adoc[Object Mapping] integrated with Spring's Conversion Service.
+* Annotation-based mapping metadata that is extensible to support other metadata formats.
+* xref:redis/transactions.adoc[Transactions] and xref:redis/pipelining.adoc[Pipelining].
+* xref:redis/redis-cache.adoc[Redis Cache] integration through Spring's Cache abstraction.
+* xref:redis/pubsub.adoc[Redis Pub/Sub Messaging] and xref:redis/redis-streams.adoc[Redis Stream] Listeners.
+* xref:redis/support-classes.adoc[Redis Collection Implementations] for Java such as `RedisList` or `RedisSet`.
+
+== Why Spring Data Redis?
+
+The Spring Framework is the leading full-stack Java/JEE application framework.
+It provides a lightweight container and a non-invasive programming model enabled by the use of dependency injection, AOP, and portable service abstractions.
+
+https://en.wikipedia.org/wiki/NoSQL[NoSQL] storage systems provide an alternative to classical RDBMS for horizontal scalability and speed.
+In terms of implementation, key-value stores represent one of the largest (and oldest) members in the NoSQL space.
+
+The Spring Data Redis (SDR) framework makes it easy to write Spring applications that use the Redis key-value store by eliminating the redundant tasks and boilerplate code required for interacting with the store through Spring's excellent infrastructure support.
+
+[[redis:architecture]]
+== Redis Support High-level View
+
+The Redis support provides several components.For most tasks, the high-level abstractions and support services are the best choice.Note that, at any point, you can move between layers.For example, you can get a low-level connection (or even the native library) to communicate directly with Redis.