Skip to content

Commit ba76c75

Browse files
mp911demp911de
committed
Migrate documentation site to Antora.
Closes #2703
1 parent e423851 commit ba76c75

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

70 files changed

+2818
-2553
lines changed

‎.gitignore

+5
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,8 @@ out
1616
work
1717
*.rdb
1818
*.aof
19+
build/
20+
node_modules
21+
node
22+
package.json
23+
package-lock.json

‎README.adoc

+4-4
Original file line numberDiff line numberDiff line change
@@ -97,10 +97,10 @@ If you'd rather like the latest snapshots of the upcoming major version, use our
9797
Having trouble with Spring Data? We’d love to help!
9898

9999
* Check the
100-
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].
100+
https://docs.spring.io/spring-data/redis/docs/reference/[reference documentation], and https://docs.spring.io/spring-data/redis/docs/current/api/[Javadocs].
101101
* 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.
102102
If you are just starting out with Spring, try one of the https://spring.io/guides[guides].
103-
* If you are upgrading, check out the https://docs.spring.io/spring-data/redis/docs/current/changelog.txt[changelog] for "`new and noteworthy`" features.
103+
* 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.
104104
* Ask a question - we monitor https://stackoverflow.com[stackoverflow.com] for questions tagged with https://stackoverflow.com/tags/spring-data[`spring-data-redis`].
105105
You can also chat with the community on https://gitter.im/spring-projects/spring-data[Gitter].
106106
* 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.
136136

137137
[source,bash]
138138
----
139-
$ ./mvnw clean install -Pdistribute
139+
$ ./mvnw clean install -Pantora
140140
----
141141

142-
The generated documentation is available from `target/site/reference/html/index.html`.
142+
The generated documentation is available from `target/antora/site/index.html`.
143143

144144
== Guides
145145

‎pom.xml

+23
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919

2020
<properties>
2121
<springdata.keyvalue>3.2.0-SNAPSHOT</springdata.keyvalue>
22+
<springdata.commons>3.2.0-SNAPSHOT</springdata.commons>
2223
<awaitility>4.0.2</awaitility>
2324
<beanutils>1.9.4</beanutils>
2425
<xstream>1.4.20</xstream>
@@ -374,6 +375,28 @@
374375
</plugins>
375376
</build>
376377
</profile>
378+
<profile>
379+
<id>antora-process-resources</id>
380+
<build>
381+
<resources>
382+
<resource>
383+
<directory>src/main/antora/resources/antora-resources</directory>
384+
<filtering>true</filtering>
385+
</resource>
386+
</resources>
387+
</build>
388+
</profile>
389+
<profile>
390+
<id>antora</id>
391+
<build>
392+
<plugins>
393+
<plugin>
394+
<groupId>io.spring.maven.antora</groupId>
395+
<artifactId>antora-maven-plugin</artifactId>
396+
</plugin>
397+
</plugins>
398+
</build>
399+
</profile>
377400
</profiles>
378401

379402
<repositories>

‎src/main/antora/antora-playbook.yml

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# 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
2+
#
3+
# The purpose of this Antora playbook is to build the docs in the current branch.
4+
antora:
5+
extensions:
6+
- '@antora/collector-extension'
7+
- require: '@springio/antora-extensions/root-component-extension'
8+
root_component_name: 'data-redis'
9+
site:
10+
title: Spring Data Redis
11+
url: https://docs.spring.io/spring-data-redis/reference/
12+
content:
13+
sources:
14+
- url: ./../../..
15+
branches: HEAD
16+
start_path: src/main/antora
17+
worktrees: true
18+
- url: https://github.com/spring-projects/spring-data-commons
19+
# Refname matching:
20+
# https://docs.antora.org/antora/latest/playbook/content-refname-matching/
21+
branches: [ main, 3.2.x ]
22+
start_path: src/main/antora
23+
asciidoc:
24+
attributes:
25+
page-pagination: ''
26+
hide-uri-scheme: '@'
27+
tabs-sync-option: '@'
28+
chomp: 'all'
29+
extensions:
30+
- '@asciidoctor/tabs'
31+
- '@springio/asciidoctor-extensions'
32+
sourcemap: true
33+
urls:
34+
latest_version_segment: ''
35+
runtime:
36+
log:
37+
failure_level: warn
38+
format: pretty
39+
ui:
40+
bundle:
41+
url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.3.5/ui-bundle.zip
42+
snapshot: true

‎src/main/antora/antora.yml

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
name: data-redis
2+
version: true
3+
title: Spring Data Redis
4+
nav:
5+
- modules/ROOT/nav.adoc
6+
ext:
7+
collector:
8+
- run:
9+
command: ./mvnw validate process-resources -Pantora-process-resources
10+
local: true
11+
scan:
12+
dir: target/classes/

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

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../../../../test/java/org/springframework/data/redis/examples

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

+47
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
* xref:index.adoc[Overview]
2+
** xref:commons/upgrade.adoc[]
3+
** xref:upgrading.adoc[]
4+
5+
6+
* xref:redis.adoc[]
7+
** xref:redis/getting-started.adoc[]
8+
** xref:redis/drivers.adoc[]
9+
** xref:redis/connection-modes.adoc[]
10+
** xref:redis/template.adoc[RedisTemplate]
11+
** xref:redis/cluster.adoc[]
12+
** xref:redis/hash-mappers.adoc[]
13+
** xref:redis/pubsub.adoc[]
14+
** xref:redis/redis-streams.adoc[]
15+
** xref:redis/redis-cache.adoc[]
16+
** xref:redis/scripting.adoc[]
17+
** xref:redis/transactions.adoc[]
18+
** xref:redis/pipelining.adoc[]
19+
** xref:redis/support-classes.adoc[]
20+
21+
* xref:repositories.adoc[]
22+
** xref:repositories/core-concepts.adoc[]
23+
** xref:repositories/definition.adoc[]
24+
** xref:repositories/create-instances.adoc[]
25+
** xref:redis/redis-repositories/usage.adoc[]
26+
** xref:repositories/object-mapping.adoc[]
27+
** xref:redis/redis-repositories/mapping.adoc[]
28+
** xref:redis/redis-repositories/keyspaces.adoc[]
29+
** xref:redis/redis-repositories/indexes.adoc[]
30+
** xref:redis/redis-repositories/expirations.adoc[]
31+
** xref:redis/redis-repositories/queries.adoc[]
32+
** xref:redis/redis-repositories/query-by-example.adoc[]
33+
** xref:redis/redis-repositories/cluster.adoc[]
34+
** xref:redis/redis-repositories/anatomy.adoc[]
35+
** xref:repositories/projections.adoc[]
36+
** xref:repositories/custom-implementations.adoc[]
37+
** xref:repositories/core-domain-events.adoc[]
38+
** xref:repositories/null-handling.adoc[]
39+
** xref:redis/redis-repositories/cdi-integration.adoc[]
40+
** xref:repositories/query-keywords-reference.adoc[]
41+
** xref:repositories/query-return-types-reference.adoc[]
42+
43+
* xref:observability.adoc[]
44+
45+
* xref:appendix.adoc[]
46+
47+
* 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

+8-3
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,12 @@
1-
[[appendix:command-reference]]
2-
[appendix]
3-
= Command Reference
1+
[[appendix]]
2+
= Appendix
43

4+
[[schema]]
5+
== Schema
6+
7+
link:https://www.springframework.org/schema/redis/spring-redis-1.0.xsd[Spring Data Redis Schema (redis-namespace)]
8+
9+
[[supported-commands]]
510
== Supported Commands
611
.Redis commands supported by `RedisTemplate`
712
[width="50%",cols="<2,^1",options="header"]

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

+2-4
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,6 @@
1-
include::../{spring-data-commons-docs}/upgrade.adoc[]
2-
3-
== What to Read Next
1+
include::{commons}@data-commons::page$upgrade.adoc[]
42

53
Once you’ve decided to upgrade your application, you can find detailed information regarding specific features in the rest of the document.
6-
You can find <<redis.upgrading,migration guides>> specific to major version migrations at the end of this document.
4+
You can find xref:upgrading.adoc#redis.upgrading[migration guides] specific to major version migrations at the end of this document.
75

86
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

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
[[spring-data-redis-reference-documentation]]
2+
= Spring Data Redis
3+
:revnumber: {version}
4+
:revdate: {localdate}
5+
:feature-scroll: true
6+
7+
_Spring Data Redis provides Redis connectivity and repository support for the Redis database.
8+
It eases development of applications with a consistent programming model that need to access Redis data sources._
9+
10+
[horizontal]
11+
xref:redis.adoc[Redis] :: Redis support and connectivity
12+
xref:repositories.adoc[Repositories] :: Redis Repositories
13+
xref:observability.adoc[Observability] :: Observability Integration
14+
https://github.com/spring-projects/spring-data-commons/wiki[Wiki] :: What's New, Upgrade Notes, Supported Versions, additional cross-version information.
15+
16+
Costin Leau, Jennifer Hickey, Christoph Strobl, Thomas Darimont, Mark Paluch, Jay Bryant
17+
18+
(C) 2008-2023 VMware, Inc.
19+
20+
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

+107
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
[[redis.observability]]
2+
= Observability
3+
4+
Getting insights from an application component about its operations, timing and relation to application code is crucial to understand latency.
5+
Spring Data Redis ships with a Micrometer integration through the Lettuce driver to collect observations during Redis interaction.
6+
Once the integration is set up, Micrometer will create meters and spans (for distributed tracing) for each Redis command.
7+
8+
To enable the integration, apply the following configuration to `LettuceClientConfiguration`:
9+
10+
[source,java]
11+
----
12+
@Configuration
13+
class ObservabilityConfiguration {
14+
15+
@Bean
16+
public ClientResources clientResources(ObservationRegistry observationRegistry) {
17+
18+
return ClientResources.builder()
19+
.tracing(new MicrometerTracingAdapter(observationRegistry, "my-redis-cache"))
20+
.build();
21+
}
22+
23+
@Bean
24+
public LettuceConnectionFactory lettuceConnectionFactory(ClientResources clientResources) {
25+
26+
LettuceClientConfiguration clientConfig = LettuceClientConfiguration.builder()
27+
.clientResources(clientResources).build();
28+
RedisConfiguration redisConfiguration = …;
29+
return new LettuceConnectionFactory(redisConfiguration, clientConfig);
30+
}
31+
}
32+
----
33+
34+
See also https://opentelemetry.io/docs/reference/specification/trace/semantic_conventions/database/#redis[OpenTelemetry Semantic Conventions] for further reference.
35+
36+
[[observability-metrics]]
37+
== Observability - Metrics
38+
39+
Below you can find a list of all metrics declared by this project.
40+
41+
[[observability-metrics-redis-command-observation]]
42+
== Redis Command Observation
43+
44+
____
45+
Timer created around a Redis command execution.
46+
____
47+
48+
**Metric name** `spring.data.redis`. **Type** `timer` and **base unit** `seconds`.
49+
50+
Fully qualified name of the enclosing class `org.springframework.data.redis.connection.lettuce.observability.RedisObservation`.
51+
52+
53+
54+
.Low cardinality Keys
55+
[cols="a,a"]
56+
|===
57+
|Name | Description
58+
|`db.operation`|Redis command value.
59+
|`db.redis.database_index`|Redis database index.
60+
|`db.system`|Database system.
61+
|`db.user`|Redis user.
62+
|`net.peer.name`|Name of the database host.
63+
|`net.peer.port`|Logical remote port number.
64+
|`net.sock.peer.addr`|Mongo peer address.
65+
|`net.sock.peer.port`|Mongo peer port.
66+
|`net.transport`|Network transport.
67+
|===
68+
69+
.High cardinality Keys
70+
[cols="a,a"]
71+
|===
72+
|Name | Description
73+
|`db.statement`|Redis statement.
74+
|`spring.data.redis.command.error`|Redis error response.
75+
|===
76+
77+
[[observability-spans]]
78+
== Observability - Spans
79+
80+
Below you can find a list of all spans declared by this project.
81+
82+
[[observability-spans-redis-command-observation]]
83+
== Redis Command Observation Span
84+
85+
> Timer created around a Redis command execution.
86+
87+
**Span name** `spring.data.redis`.
88+
89+
Fully qualified name of the enclosing class `org.springframework.data.redis.connection.lettuce.observability.RedisObservation`.
90+
91+
92+
93+
.Tag Keys
94+
|===
95+
|Name | Description
96+
|`db.operation`|Redis command value.
97+
|`db.redis.database_index`|Redis database index.
98+
|`db.statement`|Redis statement.
99+
|`db.system`|Database system.
100+
|`db.user`|Redis user.
101+
|`net.peer.name`|Name of the database host.
102+
|`net.peer.port`|Logical remote port number.
103+
|`net.sock.peer.addr`|Mongo peer address.
104+
|`net.sock.peer.port`|Mongo peer port.
105+
|`net.transport`|Network transport.
106+
|`spring.data.redis.command.error`|Redis error response.
107+
|===

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

+6-6
Original file line numberDiff line numberDiff line change
@@ -11,14 +11,14 @@ This section provides an easy-to-follow guide for getting started with the Sprin
1111
== Learning Spring
1212

1313
Spring Data uses Spring framework's
14-
{spring-framework-reference}/core.html[core] functionality, including:
14+
{spring-framework-docs}/core.html[core] functionality, including:
1515

1616

17-
* {spring-framework-reference}/core.html#beans[IoC] container
18-
* {spring-framework-reference}/core.html#validation[type conversion system]
19-
* {spring-framework-reference}/core.html#expressions[expression language]
20-
* {spring-framework-reference}/integration.html#jmx[JMX integration]
21-
* {spring-framework-reference}/data-access.html#dao-exceptions[DAO exception hierarchy].
17+
* {spring-framework-docs}/core.html#beans[IoC] container
18+
* {spring-framework-docs}/core.html#validation[type conversion system]
19+
* {spring-framework-docs}/core.html#expressions[expression language]
20+
* {spring-framework-docs}/integration.html#jmx[JMX integration]
21+
* {spring-framework-docs}/data-access.html#dao-exceptions[DAO exception hierarchy].
2222

2323
While you need not know the Spring APIs, understanding the concepts behind them is important.
2424
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

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
[[redis]]
2+
= Redis
3+
:page-section-summary-toc: 1
4+
5+
One of the key-value stores supported by Spring Data is https://redis.io[Redis].
6+
To quote the Redis project home page:
7+
8+
[quote]
9+
Redis is an advanced key-value store.
10+
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.
11+
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.
12+
Redis supports different kind of sorting abilities.
13+
14+
Spring Data Redis provides easy configuration and access to Redis from Spring applications.
15+
It offers both low-level and high-level abstractions for interacting with the store, freeing the user from infrastructural concerns.
16+
17+
Spring Data support for Redis contains a wide range of features:
18+
19+
* xref:redis/template.adoc[`RedisTemplate` and `ReactiveRedisTemplate` helper class] that increases productivity when performing common Redis operations.
20+
Includes integrated serialization between objects and values.
21+
* Exception translation into Spring's portable Data Access Exception hierarchy.
22+
* Automatic implementation of xref:repositories.adoc[Repository interfaces], including support for custom query methods.
23+
* Feature-rich xref:redis/redis-repositories/mapping.adoc[Object Mapping] integrated with Spring's Conversion Service.
24+
* Annotation-based mapping metadata that is extensible to support other metadata formats.
25+
* xref:redis/transactions.adoc[Transactions] and xref:redis/pipelining.adoc[Pipelining].
26+
* xref:redis/redis-cache.adoc[Redis Cache] integration through Spring's Cache abstraction.
27+
* xref:redis/pubsub.adoc[Redis Pub/Sub Messaging] and xref:redis/redis-streams.adoc[Redis Stream] Listeners.
28+
* xref:redis/support-classes.adoc[Redis Collection Implementations] for Java such as `RedisList` or `RedisSet`.
29+
30+
== Why Spring Data Redis?
31+
32+
The Spring Framework is the leading full-stack Java/JEE application framework.
33+
It provides a lightweight container and a non-invasive programming model enabled by the use of dependency injection, AOP, and portable service abstractions.
34+
35+
https://en.wikipedia.org/wiki/NoSQL[NoSQL] storage systems provide an alternative to classical RDBMS for horizontal scalability and speed.
36+
In terms of implementation, key-value stores represent one of the largest (and oldest) members in the NoSQL space.
37+
38+
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.
39+
40+
[[redis:architecture]]
41+
== Redis Support High-level View
42+
43+
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.

0 commit comments

Comments
 (0)