Migrate documentation to Antora.

Closes #1815
2023-08-31 13:54:00 +02:00
parent 6f5efea114
commit 1b3d9f37e3
37 changed files with 316 additions and 105 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -7,3 +7,9 @@ target/

 *.iml
 .idea
+
+build/
+node_modules
+node
+package.json
+package-lock.json
--- a/README.adoc
+++ b/README.adoc
@@ -1,5 +1,3 @@
-image:https://spring.io/badges/spring-data-couchbase/ga.svg[Spring Data Couchbase,link=https://projects.spring.io/spring-data-couchbase#quick-start] image:https://spring.io/badges/spring-data-couchbase/snapshot.svg[Spring Data Couchbase,link=https://projects.spring.io/spring-data-couchbase#quick-start]
-
 = Spring Data Couchbase image:https://jenkins.spring.io/buildStatus/icon?job=spring-data-couchbase%2Fmain&subject=Build[link=https://jenkins.spring.io/view/SpringData/job/spring-data-couchbase/] https://gitter.im/spring-projects/spring-data[image:https://badges.gitter.im/spring-projects/spring-data.svg[Gitter]]

 The primary goal of the https://www.springsource.org/spring-data[Spring Data] project is to make it easier to build
@@ -32,16 +30,15 @@ This project is lead and maintained by Couchbase, Inc.

 == Version compatibility

-`Spring-Data Couchbase 3.0.x` is the Spring Data connector for the `Couchbase Java SDK 2.x` generation.
+`Spring-Data Couchbase` is the Spring Data connector for the `Couchbase Java SDK 2.x` generation.

-Both the SDK and this Spring Data community project are major version changes with lots of differences from their
-respective previous versions.
+Both the SDK and this Spring Data community project are major version changes with lots of differences from their respective previous versions.

 Notably, this version is compatible with `Couchbase Server 4.0`, bringing support for the `N1QL` query language.

 == Code of Conduct

-This project is governed by the https://github.com/spring-projects/.github/blob/e3cc2ff230d8f1dca06535aa6b5a4a23815861d4/CODE_OF_CONDUCT.md[Spring Code of Conduct]. By participating, you are expected to uphold this code of conduct. Please report unacceptable behavior to spring-code-of-conduct@pivotal.io.
+This project is governed by the https://github.com/spring-projects/.github/blob/e3cc2ff230d8f1dca06535aa6b5a4a23815861d4/CODE_OF_CONDUCT.md[Spring Code of Conduct].By participating, you are expected to uphold this code of conduct.Please report unacceptable behavior to spring-code-of-conduct@pivotal.io.

 == Getting Started

@@ -144,14 +141,16 @@ You can also chat with the community on https://gitter.im/spring-projects/spring

 == Reporting Issues

-Spring Data uses JIRA as issue tracking system to record bugs and feature requests. If you want to raise an issue, please follow the recommendations below:
+Spring Data uses GitHub as issue tracking system to record bugs and feature requests.
+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-couchbase/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-couchbase/issues/new[create a new issue].
+* If the issue does not already exist, https://github.com/spring-projects/spring-data-couchbase/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 that you are using and JVM version.
-* If you need to paste code, or include a stack trace use JIRA `{code}…{code}` 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.
+* 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.

 == Building from Source

@@ -173,10 +172,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`.

 === Building and staging reference documentation for review

--- a/pom.xml
+++ b/pom.xml
@@ -319,6 +319,31 @@
        </plugins>
    </build>

+	<profiles>
+		<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>
 		<repository>
 			<id>spring-snapshot</id>
--- a/src/main/antora/.github/workflows/deploy-docs.yml
+++ b/src/main/antora/.github/workflows/deploy-docs.yml
@@ -0,0 +1,33 @@
+name: Deploy Docs
+on:
+  push:
+    branches-ignore: [ gh-pages ]
+    tags: '**'
+  repository_dispatch:
+    types: request-build-reference # legacy
+  #schedule:
+  #- cron: '0 10 * * *' # Once per day at 10am UTC
+  workflow_dispatch:
+permissions:
+  actions: write
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    # FIXME: enable when pushed to spring-projects
+    # if: github.repository_owner == 'spring-projects'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          ref: docs-build
+          fetch-depth: 1
+      - name: Dispatch (partial build)
+        if: github.ref_type == 'branch'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD) -f build-refname=${{ github.ref_name }}
+      - name: Dispatch (full build)
+        if: github.ref_type == 'tag'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD)
--- a/src/main/antora/antora-playbook.yml
+++ b/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-couchbase'
+site:
+  title: Spring Data Couchbase
+  url: https://docs.spring.io/spring-data-couchbase/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
--- a/src/main/antora/antora.yml
+++ b/src/main/antora/antora.yml
@@ -0,0 +1,12 @@
+name: data-couchbase
+version: true
+title: Spring Data Couchbase
+nav:
+  - modules/ROOT/nav.adoc
+ext:
+  collector:
+    - run:
+        command: ./mvnw validate process-resources -am -Pantora-process-resources
+        local: true
+      scan:
+        dir: target/classes/
--- a/src/main/antora/modules/ROOT/nav.adoc
+++ b/src/main/antora/modules/ROOT/nav.adoc
@@ -0,0 +1,31 @@
+* xref:index.adoc[Overview]
+** xref:commons/upgrade.adoc[]
+** xref:commons/migrating.adoc[]
+
+* xref:couchbase.adoc[]
+** xref:couchbase/configuration.adoc[]
+** xref:couchbase/entity.adoc[]
+** xref:couchbase/autokeygeneration.adoc[]
+** xref:couchbase/template.adoc[]
+** xref:couchbase/transactions.adoc[]
+** xref:couchbase/collections.adoc[]
+** xref:couchbase/fieldlevelencryption.adoc[]
+** xref:couchbase/ansijoins.adoc[]
+** xref:couchbase/caching.adoc[]
+
+* xref:repositories.adoc[]
+** xref:repositories/core-concepts.adoc[]
+** xref:repositories/definition.adoc[]
+** xref:couchbase/repository.adoc[]
+** xref:couchbase/reactiverepository.adoc[]
+** xref:repositories/create-instances.adoc[]
+** xref:repositories/query-methods-details.adoc[]
+** xref:repositories/projections.adoc[]
+** xref:repositories/custom-implementations.adoc[]
+** xref:repositories/core-domain-events.adoc[]
+** xref:repositories/core-extensions.adoc[]
+** xref:repositories/null-handling.adoc[]
+** xref:repositories/query-keywords-reference.adoc[]
+** xref:repositories/query-return-types-reference.adoc[]
+
+* https://github.com/spring-projects/spring-data-commons/wiki[Wiki]
--- a/src/main/antora/modules/ROOT/pages/commons/migrating.adoc
+++ b/src/main/antora/modules/ROOT/pages/commons/migrating.adoc
@@ -12,45 +12,48 @@ Since the main objective was to migrate from the Java SDK 2 to 3, configuration

 IMPORTANT: XML Configuration support has been dropped, so only java/annotation based configuration is supported.

-Your configuration still has to extend the `AbstractCouchbaseConfiguration`, but since RBAC (role-based access control) is now mandatory, different properties need to be overridden in order to be configured: `getConnectionString`, `getUserName`, `getPassword` and `getBucketName`. If you want to use a non-default scope optionally you can override the `getScopeName` method. Note that if you want to use certificate based authentication or you need to customize the password authentication, the `authenticator` method can be overridden to perform this task.
+Your configuration still has to extend the `AbstractCouchbaseConfiguration`, but since RBAC (role-based access control) is now mandatory, different properties need to be overridden in order to be configured: `getConnectionString`, `getUserName`, `getPassword` and `getBucketName`.If you want to use a non-default scope optionally you can override the `getScopeName` method.Note that if you want to use certificate based authentication or you need to customize the password authentication, the `authenticator` method can be overridden to perform this task.

 The new SDK still has an environment that is used to configure it, so you can override the `configureEnvironment` method and supply custom configuration if needed.

-For more information, see <<couchbase.configuration>>.
+For more information, see xref:couchbase/configuration.adoc[Installation & Configuration].

+[[spring-boot-version-compatibility]]
 === Spring Boot Version Compatibility

-Spring Boot 2.3.x or higher depends on Spring Data Couchbase 4.x. Earlier versions of Couchbase are not available because SDK 2 and 3 cannot live on the same classpath.
+Spring Boot 2.3.x or higher depends on Spring Data Couchbase 4.x.Earlier versions of Couchbase are not available because SDK 2 and 3 cannot live on the same classpath.

 [[couchbase.migrating.entities]]


+[[entities]]
 == Entities
 How to deal with entities has not changed, although since the SDK now does not ship annotations anymore only Spring-Data related annotations are supported.

 Specifically:

- - `com.couchbase.client.java.repository.annotation.Id` became `import org.springframework.data.annotation.Id`
- - `com.couchbase.client.java.repository.annotation.Field` became `import org.springframework.data.couchbase.core.mapping.Field`
+- `com.couchbase.client.java.repository.annotation.Id` became `import org.springframework.data.annotation.Id`
+- `com.couchbase.client.java.repository.annotation.Field` became `import org.springframework.data.couchbase.core.mapping.Field`

 The `org.springframework.data.couchbase.core.mapping.Document` annotation stayed the same.

-For more information, see <<couchbase.entity>>.
+For more information, see xref:couchbase/entity.adoc[Modeling Entities].


 [[couchbase.migrating.indexes]]
 == Automatic Index Management

-Automatic Index Management has been redesigned to allow more flexible indexing. New annotations have been introduced and old ones like `@ViewIndexed`, `@N1qlSecondaryIndexed` and `@N1qlPrimaryIndexed` were removed.
+Automatic Index Management has been redesigned to allow more flexible indexing.
+New annotations have been introduced and old ones like `@ViewIndexed`, `@N1qlSecondaryIndexed` and `@N1qlPrimaryIndexed` were removed.

-For more information, see <<couchbase.repository.indexing>>.
+For more information, see xref:couchbase/repository.adoc#couchbase.repository.indexing[Automatic Index Management].

 [[couchbase.migrating.template]]
 == Template and ReactiveTemplate

 Since the Couchbase SDK 3 removes support for `RxJava` and instead adds support for `Reactor`, both the `couchbaseTemplate` as well as the `reactiveCouchbaseTemplate` can be directly accessed from the `AbstractCouchbaseConfiguration`.

-The template has been completely overhauled so that it now uses a fluent API to configure instead of many method overloads. This has the advantage that in the future we are able to extend the functionality without having to introduce more and more overloads that make it complicated to navigate.
+The template has been completely overhauled so that it now uses a fluent API to configure instead of many method overloads.This has the advantage that in the future we are able to extend the functionality without having to introduce more and more overloads that make it complicated to navigate.

 The following table describes the method names in 3.x and compares them to their 4.x equivalents:

@@ -113,14 +116,14 @@ In addition, the following methods have been added which were not available in 3

 We tried to unify and align the APIs more closely to the underlying SDK semantics so they are easier to correlate and navigate.

-For more information, see <<couchbase.template>>.
+For more information, see xref:couchbase/template.adoc[Template & direct operations].

 [[couchbase.migrating.repository]]
 == Repositories & Queries

-  - `org.springframework.data.couchbase.core.query.Query` became `org.springframework.data.couchbase.repository.Query`
-  - `org.springframework.data.couchbase.repository.ReactiveCouchbaseSortingRepository` has been removed. Consider extending  `ReactiveSortingRepository` or `ReactiveCouchbaseRepository`
-  - `org.springframework.data.couchbase.repository.CouchbasePagingAndSortingRepository` has been removed. Consider extending  `PagingAndSortingRepository` or `CouchbaseRepository`
+- `org.springframework.data.couchbase.core.query.Query` became `org.springframework.data.couchbase.repository.Query`
+- `org.springframework.data.couchbase.repository.ReactiveCouchbaseSortingRepository` has been removed.Consider extending  `ReactiveSortingRepository` or `ReactiveCouchbaseRepository`
+- `org.springframework.data.couchbase.repository.CouchbasePagingAndSortingRepository` has been removed.Consider extending  `PagingAndSortingRepository` or `CouchbaseRepository`


 IMPORTANT: Support for views has been removed and N1QL queries are now the first-class citizens for all custom repository methods as well as the built-in ones by default.
@@ -151,9 +154,10 @@ public class MyService {
 ----
 ====

-See <<couchbase.repository>> for more information.
+See xref:couchbase/repository.adoc[Couchbase repositories] for more information.


+[[full-text-search-fts]]
 == Full Text Search (FTS)

 The FTS API has been simplified and now can be accessed via the `Cluster` class:
@@ -193,4 +197,4 @@ public class MyService {
 ----
 ====

-See link:https://docs.couchbase.com/java-sdk/current/howtos/full-text-searching-with-sdk.html[the FTS Documentation] for more information.
+See link:https://docs.couchbase.com/java-sdk/current/howtos/full-text-searching-with-sdk.html[the FTS Documentation] for more information.
--- a/src/main/antora/modules/ROOT/pages/commons/upgrade.adoc
+++ b/src/main/antora/modules/ROOT/pages/commons/upgrade.adoc
@@ -0,0 +1 @@
+include::{commons}@data-commons::page$upgrade.adoc[]
--- a/src/main/antora/modules/ROOT/pages/couchbase.adoc
+++ b/src/main/antora/modules/ROOT/pages/couchbase.adoc
@@ -0,0 +1,15 @@
+[[couchbase.core]]
+= Couchbase Support
+:page-section-summary-toc: 1
+
+Spring Data support for Couchbase contains a wide range of features:
+
+* Spring configuration support with xref:couchbase/configuration.adoc[Java-based `@Configuration` classes].
+* The xref:couchbase/template.adoc[`CouchbaseTemplate` and `ReactiveCouchbaseTemplate`] helper classes that provide object mapping between Couchbase collections and POJOs.
+* xref:couchbase/template.adoc#exception-translation[Exception translation] into Spring's portable {spring-data-commons-docs-url}data-access.html#dao-exceptions[Data Access Exception Hierarchy].
+* Feature rich object mapping integrated with _Spring's_ {spring-data-commons-docs-url}core.html#core-convert[Conversion Service].
+* Annotation-based mapping metadata that is extensible to support other metadata formats.
+* 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]CouchbaseTemplate` or the `Repository` support, both of which use the rich object-mapping functionality.
+Spring Data Couchbase uses consistent naming conventions on objects in various APIs to those found in the Couchbase Java SDK so that they are familiar and so that you can map your existing knowledge onto the Spring APIs.
--- a/src/main/antora/modules/ROOT/pages/couchbase/ansijoins.adoc
+++ b/src/main/antora/modules/ROOT/pages/couchbase/ansijoins.adoc
@@ -58,16 +58,19 @@ List<Book> books;
 [[couchbase.ansijoins.joinhints]]
 == ANSI Join Hints

+[[use-index-hint]]
 === Use Index Hint

 `index` element on the `@N1qlJoin` can be used to provided the hint for the `lks` (current entity) index and `rightIndex`
 element can be used to provided the `rks` (associated entity) index.

+[[hash-join-hint]]
 === Hash Join Hint

 If the join type is going to be hash join, the hash side can be specified for the `rks` (associated entity).
 If the associated entity is on the build side, it can be specified as `HashSide.BUILD` else `HashSide.PROBE`.

+[[use-keys-hint]]
 === Use Keys Hint

-`keys` element on the `@N1qlJoin` annotation can be used to specify unique document keys to restrict the join key space.
+`keys` element on the `@N1qlJoin` annotation can be used to specify unique document keys to restrict the join key space.
--- a/src/main/antora/modules/ROOT/pages/couchbase/autokeygeneration.adoc
+++ b/src/main/antora/modules/ROOT/pages/couchbase/autokeygeneration.adoc
@@ -4,8 +4,8 @@
 This chapter describes how couchbase document keys can be auto-generated using builtin mechanisms.
 There are two types of auto-generation strategies supported.

- <<couchbase.autokeygeneration.usingattributes>>
- <<couchbase.autokeygeneration.unique>>
+- xref:couchbase/autokeygeneration.adoc#couchbase.autokeygeneration.usingattributes[Key generation using attributes]
+- xref:couchbase/autokeygeneration.adoc#couchbase.autokeygeneration.unique[Key generation using uuid]

 NOTE: The maximum key length supported by couchbase is 250 bytes.

@@ -75,4 +75,4 @@ public class User {
     ...
 }
 ----
-====
+====
--- a/src/main/antora/modules/ROOT/pages/couchbase/caching.adoc
+++ b/src/main/antora/modules/ROOT/pages/couchbase/caching.adoc
--- a/src/main/antora/modules/ROOT/pages/couchbase/collections.adoc
+++ b/src/main/antora/modules/ROOT/pages/couchbase/collections.adoc
@@ -7,14 +7,17 @@ The https://github.com/couchbaselabs/try-cb-spring[try-cb-spring] sample applica

 The 2021 Couchbase Connect presentation on Collections in Spring Data can be found at https://www.youtube.com/watch?v=MrplTeEFItk[Presentation Only] and https://web.cvent.com/hub/events/1dce8283-986d-4de9-8368-94c98f60df01/sessions/9ee89a85-833c-4e0c-81b0-807864fa351b?goBackHref=%2Fevents%2F1dce8283-986d-4de9-8368-94c98f60df01%2Fsessions&goBackName=Add%2FView+Sessions&goBackTab=all[Presentation with Slide Deck]

+[[requirements]]
 == Requirements

 - Couchbase Server 7.0 or above.
 - Spring Data Couchbase 4.3.1 or above.

+[[getting-started-configuration]]
 == Getting Started & Configuration


+[[scope-and-collection-specification]]
 === Scope and Collection Specification
 There are several mechanisms of specifying scopes and collections, and these may be combined, or one mechanism may override another. 
 First some definitions for scopes and collections. An unspecified scope indicates that the default scope is to be used, likewise, an 
--- a/src/main/antora/modules/ROOT/pages/couchbase/configuration.adoc
+++ b/src/main/antora/modules/ROOT/pages/couchbase/configuration.adoc
@@ -9,6 +9,7 @@ This chapter describes the common installation and configuration steps needed wh
 All versions intended for production use are distributed across Maven Central and the Spring release repository.
 As a result, the library can be included like any other maven dependency:

+[[configuration]]
 == Configuration
 .Including the dependency through maven
 ====
@@ -27,6 +28,7 @@ This will pull in several dependencies, including the underlying Couchbase Java
 You can also grab snapshots from the https://repo.spring.io/ui/repos/tree/General/snapshot/org/springframework/data/spring-data-couchbase[spring snapshot repository] ( \https://repo.spring.io/snapshot ) and milestone releases from the https://repo.spring.io/ui/repos/tree/General/milestone/org/springframework/data/spring-data-couchbase[spring milestone repository] ( \https://repo.spring.io/milestone ).
 Here is an example on how to use the current SNAPSHOT dependency:

+[[snapshot-configuration]]
 == Snapshot Configuration

 .Using a snapshot version
@@ -47,6 +49,7 @@ Here is an example on how to use the current SNAPSHOT dependency:
 ----
 ====

+[[overriding-the-couchbase-sdk-version]]
 == Overriding the Couchbase SDK Version

 Some users may wish to use a Couchbase Java SDK version different from the one referenced in a Spring Data Couchbase release for the purpose of obtaining bug and vulnerability fixes.  Since Couchbase Java SDK minor version releases are backwards compatible, this version of Spring Data Couchbase is compatible and supported with any 3.x version of the Couchbase Java SDK newer than the one specified in the release dependencies.  To change the Couchbase Java SDK version used by Spring Data Couchbase, simply override the dependency in the application pom.xml as follows:
@@ -111,7 +114,7 @@ Only Java config is supported (XML config has been removed in 4.0).
 [[configuration-java]]
 == Annotation-based Configuration ("JavaConfig")

-To get started, all you need to do is subclcass the `AbstractCouchbaseConfiguration` and implement the abstract methods.
+To get started, all you need to do is subclass the `AbstractCouchbaseConfiguration` and implement the abstract methods.

 .Extending the `AbstractCouchbaseConfiguration`
 ====
@@ -165,27 +168,31 @@ Override `typeKey()` (for example to return `MappingCouchbaseConverter.TYPEKEY_S
 name of said attribute.

 If you start your application, you should see Couchbase INFO level logging in the logs, indicating that the underlying
-Couchbase Java SDK is connecting to the database. If any errors are reported, make sure that the given credentials
+Couchbase Java SDK is connecting to the database.If any errors are reported, make sure that the given credentials
 and host information are correct.


+[[configuring-multiple-buckets]]
 == Configuring Multiple Buckets

-To leverage multi-bucket repositories, implement the methods below in your Config class.  The config*OperationsMapping methods configure the mapping of entity-objects to buckets.  Be careful with the method names - using a method name that is a Bean will result in the value of that bean being used instead of the result of the method. 
+To leverage multi-bucket repositories, implement the methods below in your Config class.
+The config*OperationsMapping methods configure the mapping of entity-objects to buckets.
+Be careful with the method names - using a method name that is a Bean will result in the value of that bean being used instead of the result of the method.

-This example maps Person -> protected,  User -> mybucket, and everything else goes to getBucketName(). Note that this only maps calls through the Repository.
+This example maps Person -> protected, User -> mybucket, and everything else goes to getBucketName().
+Note that this only maps calls through the Repository.

 ====
 [source,java]
 ----
-@Override 
+@Override
 public void configureReactiveRepositoryOperationsMapping(ReactiveRepositoryOperationsMapping baseMapping) {
 try {
  ReactiveCouchbaseTemplate personTemplate = myReactiveCouchbaseTemplate(myCouchbaseClientFactory("protected"),new MappingCouchbaseConverter());
  baseMapping.mapEntity(Person.class,  personTemplate); // Person goes in "protected" bucket
  ReactiveCouchbaseTemplate userTemplate = myReactiveCouchbaseTemplate(myCouchbaseClientFactory("mybucket"),new MappingCouchbaseConverter());
  baseMapping.mapEntity(User.class,  userTemplate); // User goes in "mybucket"
-  // everything else goes in getBucketName() 
+  // everything else goes in getBucketName()
 } catch (Exception e) {
  throw e;
 }
@@ -197,7 +204,7 @@ public void configureRepositoryOperationsMapping(RepositoryOperationsMapping bas
  baseMapping.mapEntity(Person.class,  personTemplate); // Person goes in "protected" bucket
  CouchbaseTemplate userTemplate = myCouchbaseTemplate(myCouchbaseClientFactory("mybucket"),new MappingCouchbaseConverter());
  baseMapping.mapEntity(User.class,  userTemplate); // User goes in "mybucket"
-  // everything else goes in getBucketName() 
+  // everything else goes in getBucketName()
 } catch (Exception e) {
  throw e;
 }
@@ -210,7 +217,7 @@ public ReactiveCouchbaseTemplate myReactiveCouchbaseTemplate(CouchbaseClientFact
 return new ReactiveCouchbaseTemplate(couchbaseClientFactory, mappingCouchbaseConverter);
 }

-// do not use couchbaseTemplate for the name of this method, otherwise the value of that been 
+// do not use couchbaseTemplate for the name of this method, otherwise the value of that been
 // will be used instead of the result from this call (the client factory arg is different)
 public CouchbaseTemplate myCouchbaseTemplate(CouchbaseClientFactory couchbaseClientFactory,
  MappingCouchbaseConverter mappingCouchbaseConverter) {
--- a/src/main/antora/modules/ROOT/pages/couchbase/entity.adoc
+++ b/src/main/antora/modules/ROOT/pages/couchbase/entity.adoc
@@ -3,7 +3,7 @@

 This chapter describes how to model Entities and explains their counterpart representation in Couchbase Server itself.

-include::{spring-data-commons-docs}/object-mapping.adoc[leveloffset=+1]
+include::{commons}@data-commons::page$object-mapping.adoc[leveloffset=+1]

 [[basics]]
 == Documents and Fields
--- a/src/main/antora/modules/ROOT/pages/couchbase/fieldlevelencryption.adoc
+++ b/src/main/antora/modules/ROOT/pages/couchbase/fieldlevelencryption.adoc
@@ -3,16 +3,20 @@

 Couchbase supports https://docs.couchbase.com/java-sdk/current/howtos/encrypting-using-sdk.html[Field Level Encryption]. This section documents how to use it with Spring Data Couchbase.

+[[requirements]]
 == Requirements

 - Spring Data Couchbase 5.0.0-RC1 or above.

+[[overview]]
 == Overview
 Fields annotated with com.couchbase.client.java.encryption.annotation.Encrypted (@Encrypted) will be automatically encrypted on write and decrypted on read. Unencrypted fields can be migrated to encrypted by specifying @Encrypted(migration = Encrypted.Migration.FROM_UNENCRYPTED).


+[[getting-started-configuration]]
 == Getting Started & Configuration

+[[dependencies]]
 === Dependencies

 Field Level Encryption is available with the dependency ( see https://docs.couchbase.com/java-sdk/current/howtos/encrypting-using-sdk.html[Field Level Encryption] )
@@ -25,6 +29,7 @@ HashiCorp Vault Transit integration requires https://docs.spring.io/spring-vault
    <groupId>org.springframework.vault</groupId>
    <artifactId>spring-vault-core</artifactId>
 ```
+[[providing-a-cryptomanager]]
 === Providing a CryptoManager

 A CryptoManager needs to be provided by overriding the cryptoManager() method in AbstractCouchbaseConfiguration. This CryptoManager will be used by Spring Data Couchbase and also by Couchbase Java SDK direct calls made from a CouchbaseClientFactory.
@@ -47,12 +52,14 @@ protected CryptoManager cryptoManager() {
 }
 ```

+[[defining-a-field-as-encrypted-]]
 === Defining a Field as Encrypted.

 1. @Encrypted defines a field as encrypted.
 2. @Encrypted(migration = Encrypted.Migration.FROM_UNENCRYPTED) defines a field that may or may not be encrypted when read. It will be encrypted when written.
 3. @Encrypted(encrypter = "<encrypterAlias>") specifies the alias of the encrypter to use for encryption. Note this is not the algorithm, but the name specified when adding the encrypter to the CryptoManager. 
 
+[[example]]
 === Example
 .AbstractCouchbaseConfiguration
 ====
--- a/src/main/antora/modules/ROOT/pages/couchbase/reactiverepository.adoc
+++ b/src/main/antora/modules/ROOT/pages/couchbase/reactiverepository.adoc
@@ -5,7 +5,7 @@
 == Introduction

 This chapter describes the reactive repository support for couchbase.
-This builds on the core repository support explained in <<couchbase.repository>>.
+This builds on the core repository support explained in xref:couchbase/repository.adoc[Couchbase repositories].
 So make sure you’ve got a sound understanding of the basic concepts explained there.

 [[couchbase.reactiverepository.libraries]]
@@ -101,4 +101,4 @@ public class PersonRepositoryTests {
 [[couchbase.reactiverepository.querying]]
 == Repositories and Querying

-Spring Data's Reactive Couchbase comes with full querying support already provided by the blocking <<couchbase.repository.querying>>
+Spring Data's Reactive Couchbase comes with full querying support already provided by the blocking xref:couchbase/repository.adoc#couchbase.repository.querying[Repositories and Querying]
--- a/src/main/antora/modules/ROOT/pages/couchbase/repository.adoc
+++ b/src/main/antora/modules/ROOT/pages/couchbase/repository.adoc
@@ -3,9 +3,10 @@

 The goal of Spring Data repository abstraction is to significantly reduce the amount of boilerplate code required to implement data access layers for various persistence stores.

-By default, operations are backed by Key/Value if they are single-document operations and the ID is known. For all other operations by default N1QL queries are generated, and as a result proper indexes must be created for performant data access.
+By default, operations are backed by Key/Value if they are single-document operations and the ID is known.
+For all other operations by default N1QL queries are generated, and as a result proper indexes must be created for performant data access.

-Note that you can tune the consistency you want for your queries (see <<couchbase.repository.consistency>>) and have different repositories backed by different buckets (see <<couchbase.repository.multibucket>>)
+Note that you can tune the consistency you want for your queries (see xref:couchbase/repository.adoc#couchbase.repository.consistency[Querying with consistency]) and have different repositories backed by different buckets (see <<couchbase.repository.multibucket>>)

 [[couchbase.repository.configuration]]
 == Configuration
@@ -360,6 +361,7 @@ public interface AirportRepository extends PagingAndSortingRepository<Airport, S
 ----
 ====

+[[dto-projections]]
 === DTO Projections

 Spring Data Repositories usually return the domain model when using query methods.
--- a/src/main/antora/modules/ROOT/pages/couchbase/template.adoc
+++ b/src/main/antora/modules/ROOT/pages/couchbase/template.adoc
@@ -130,3 +130,18 @@ couchbaseTemplate.mutateInById(User.class)
    .one(user);
 ----
 ====
+
+[[exception-translation]]
+== Exception Translation
+
+The Spring Framework provides exception translation for a wide variety of database and mapping technologies.
+This has traditionally been for JDBC and JPA.
+Spring Data Couchbase extends this feature to Couchbase by providing an implementation of the `org.springframework.dao.support.PersistenceExceptionTranslator` interface.
+
+The motivation behind mapping to Spring's {spring-data-commons-docs-url}html/dao.html#dao-exceptions[consistent data access exception hierarchy]
+is to let you write portable and descriptive exception handling code without resorting to coding against and handling specific Couchbase exceptions.
+All of Spring's data access exceptions are inherited from the
+`DataAccessException` class, so you can be sure that you can catch all database-related exceptions within a single try-catch block.
+
+`ReactiveCouchbase` propagates exceptions as early as possible.
+Exceptions that occur during the processing of the reactive sequence are emitted as error signals.
--- a/src/main/antora/modules/ROOT/pages/couchbase/transactions.adoc
+++ b/src/main/antora/modules/ROOT/pages/couchbase/transactions.adoc
@@ -3,6 +3,7 @@

 Couchbase supports https://docs.couchbase.com/server/current/learn/data/transactions.html[Distributed Transactions]. This section documents how to use it with Spring Data Couchbase.

+[[requirements]]
 == Requirements

 - Couchbase Server 6.6.1 or above.
@@ -10,9 +11,11 @@ Couchbase supports https://docs.couchbase.com/server/current/learn/data/transact
 - NTP should be configured so nodes of the Couchbase cluster are in sync with time. The time being out of sync will not cause incorrect behavior, but can impact metadata cleanup.
 - The entity class must have an `@Version Long` property to hold the CAS value of the document.

+[[overview]]
 == Overview
 The Spring Data Couchbase template operations insert, find, replace and delete and repository methods that use those calls can participate in a Couchbase Transaction. They can be executed in a transaction by using the @Transactional annotation, the CouchbaseTransactionalOperator, or in the lambda of a Couchbase Transaction.  

+[[getting-started-configuration]]
 == Getting Started & Configuration

 Couchbase Transactions are normally leveraged with a method annotated with @Transactional.
@@ -20,6 +23,7 @@ The @Transactional operator is implemented with the CouchbaseTransactionManager
 Couchbase Transactions can be used without defining a service class by using CouchbaseTransactionOperator which is also supplied as a bean in AbtractCouchbaseConfiguration.
 Couchbase Transactions can also be used directly using Spring Data Couchbase operations within a lambda https://docs.couchbase.com/server/current/learn/data/transactions.html#using-transactions[Using Transactions]

+[[transactions-with-transactional]]
 == Transactions with @Transactional

@Transactional defines as transactional a method or all methods on a class. 
@@ -27,6 +31,7 @@ Couchbase Transactions can also be used directly using Spring Data Couchbase ope
 When this annotation is declared at the class level, it applies as a default
 to all methods of the declaring class and its subclasses.
 
+[[-attribute-semantics]]
 ===  Attribute Semantics
 
 In this release, the Couchbase Transactions ignores the rollback attributes. 
@@ -120,6 +125,7 @@ Functioning of the  @Transactional method annotation requires
 method from the same class will not invoke the Method Interceptor that does the transaction processing.
 ====

+[[transactions-with-couchbasetransactionaloperator]]
 == Transactions with CouchbaseTransactionalOperator

 CouchbaseTransactionalOperator can be used to construct a transaction in-line without creating a service class that uses @Transactional.
@@ -140,6 +146,7 @@ Flux<Person> result = txOperator.execute((ctx) ->
 ----
 ====

+[[transactions-directly-with-the-sdk]]
 == Transactions Directly with the SDK

 Spring Data Couchbase works seamlessly with the Couchbase Java SDK for transaction processing. Spring Data Couchbase operations that
--- a/src/main/antora/modules/ROOT/pages/index.adoc
+++ b/src/main/antora/modules/ROOT/pages/index.adoc
@@ -0,0 +1,20 @@
+[[spring-data-couchbase-reference-documentation]]
+= Spring Data Couchbase
+:revnumber: {version}
+:revdate: {localdate}
+:feature-scroll: true
+
+_Spring Data Couchbase provides repository support for the Couchbase database.
+It eases development of applications with a consistent programming model that need to access Couchbase data sources._
+
+[horizontal]
+xref:couchbase.adoc[Couchbase] :: Couchbase support and connectivity
+xref:repositories.adoc[Repositories] :: Couchbase Repositories
+xref:commons/migrating.adoc[Migration] :: Migration Guides
+https://github.com/spring-projects/spring-data-commons/wiki[Wiki] :: What's New, Upgrade Notes, Supported Versions, additional cross-version information.
+
+Michael Nitschinger, Oliver Gierke, Simon Basle, Michael Reiche, Tigran Babloyan
+
+(C) 2014-2023 The original author(s)
+
+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.
--- a/src/main/antora/modules/ROOT/pages/repositories.adoc
+++ b/src/main/antora/modules/ROOT/pages/repositories.adoc
@@ -0,0 +1,8 @@
+[[couchbase.repositories]]
+= Repositories
+:page-section-summary-toc: 1
+
+This chapter explains the basic foundations of Spring Data repositories and Couchbase specifics.
+Before continuing to the Couchbase specifics, make sure you have a sound understanding of the basic concepts.
+
+The goal of the Spring Data repository abstraction is to significantly reduce the amount of boilerplate code required to implement data access layers for various persistence stores.
--- a/src/main/antora/modules/ROOT/pages/repositories/core-concepts.adoc
+++ b/src/main/antora/modules/ROOT/pages/repositories/core-concepts.adoc
@@ -0,0 +1,4 @@
+include::{commons}@data-commons::page$repositories/core-concepts.adoc[]
+
+[[couchbase.entity-persistence.state-detection-strategies]]
+include::{commons}@data-commons::page$is-new-state-detection.adoc[leveloffset=+1]
--- a/src/main/antora/modules/ROOT/pages/repositories/core-domain-events.adoc
+++ b/src/main/antora/modules/ROOT/pages/repositories/core-domain-events.adoc
@@ -0,0 +1 @@
+include::{commons}@data-commons::page$repositories/core-domain-events.adoc[]
--- a/src/main/antora/modules/ROOT/pages/repositories/core-extensions.adoc
+++ b/src/main/antora/modules/ROOT/pages/repositories/core-extensions.adoc
@@ -0,0 +1 @@
+include::{commons}@data-commons::page$repositories/core-extensions.adoc[]
--- a/src/main/antora/modules/ROOT/pages/repositories/create-instances.adoc
+++ b/src/main/antora/modules/ROOT/pages/repositories/create-instances.adoc
@@ -0,0 +1 @@
+include::{commons}@data-commons::page$repositories/create-instances.adoc[]
--- a/src/main/antora/modules/ROOT/pages/repositories/custom-implementations.adoc
+++ b/src/main/antora/modules/ROOT/pages/repositories/custom-implementations.adoc
@@ -0,0 +1 @@
+include::{commons}@data-commons::page$repositories/custom-implementations.adoc[]
--- a/src/main/antora/modules/ROOT/pages/repositories/definition.adoc
+++ b/src/main/antora/modules/ROOT/pages/repositories/definition.adoc
@@ -0,0 +1 @@
+include::{commons}@data-commons::page$repositories/definition.adoc[]
--- a/src/main/antora/modules/ROOT/pages/repositories/null-handling.adoc
+++ b/src/main/antora/modules/ROOT/pages/repositories/null-handling.adoc
@@ -0,0 +1 @@
+include::{commons}@data-commons::page$repositories/null-handling.adoc[]
--- a/src/main/antora/modules/ROOT/pages/repositories/projections.adoc
+++ b/src/main/antora/modules/ROOT/pages/repositories/projections.adoc
@@ -0,0 +1 @@
+include::{commons}@data-commons::page$repositories/projections.adoc[]
--- a/src/main/antora/modules/ROOT/pages/repositories/query-keywords-reference.adoc
+++ b/src/main/antora/modules/ROOT/pages/repositories/query-keywords-reference.adoc
@@ -0,0 +1 @@
+include::{commons}@data-commons::page$repositories/query-keywords-reference.adoc[]
--- a/src/main/antora/modules/ROOT/pages/repositories/query-methods-details.adoc
+++ b/src/main/antora/modules/ROOT/pages/repositories/query-methods-details.adoc
@@ -0,0 +1 @@
+include::{commons}@data-commons::page$repositories/query-methods-details.adoc[]
--- a/src/main/antora/modules/ROOT/pages/repositories/query-return-types-reference.adoc
+++ b/src/main/antora/modules/ROOT/pages/repositories/query-return-types-reference.adoc
@@ -0,0 +1 @@
+include::{commons}@data-commons::page$repositories/query-return-types-reference.adoc[]
--- a/src/main/antora/resources/antora-resources/antora.yml
+++ b/src/main/antora/resources/antora-resources/antora.yml
@@ -0,0 +1,18 @@
+version: ${antora-component.version}
+prerelease: ${antora-component.prerelease}
+
+asciidoc:
+  attributes:
+    version: ${project.version}
+    springversionshort: ${spring.short}
+    springversion: ${spring}
+    attribute-missing: 'warn'
+    commons: ${springdata.commons.docs}
+    include-xml-namespaces: false
+    spring-data-commons-docs-url: https://docs.spring.io/spring-data-commons/reference
+    spring-data-commons-javadoc-base: https://docs.spring.io/spring-data/commons/docs/${springdata.commons}/api/
+    spring-framework-docs: https://docs.spring.io/spring-framework/reference/{springversionshort}
+    spring-framework-javadoc: https://docs.spring.io/spring-framework/docs/${spring}/javadoc-api
+    springhateoasversion: ${spring-hateoas}
+    releasetrainversion: ${releasetrain}
+    store: Couchbase
--- a/src/main/asciidoc/index.adoc
+++ b/src/main/asciidoc/index.adoc
@@ -1,43 +0,0 @@
-= Spring Data Couchbase - Reference Documentation
-Michael Nitschinger, Oliver Gierke, Simon Basle, Michael Reiche, Tigran Babloyan
-:revnumber: {version}
-:revdate: {localdate}
-:spring-data-commons-docs: ../../../../spring-data-commons/src/main/asciidoc
-
-(C) 2014-2023 The original author(s).
-
-NOTE: 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.
-
-toc::[]
-
-include::preface.adoc[]
-include::{spring-data-commons-docs}/upgrade.adoc[leveloffset=+1]
-
-[[reference]]
-= Reference Documentation
-
-:leveloffset: +1
-include::configuration.adoc[]
-include::entity.adoc[]
-include::autokeygeneration.adoc[]
-include::{spring-data-commons-docs}/repositories.adoc[]
-include::repository.adoc[]
-include::reactiverepository.adoc[]
-include::template.adoc[]
-include::transactions.adoc[]
-include::collections.adoc[]
-include::fieldlevelencryption.adoc[]
-include::ansijoins.adoc[]
-include::caching.adoc[]
-:leveloffset: -1
-
-[[appendix]]
-= Appendix
-
-:numbered!:
-:leveloffset: +1
-include::{spring-data-commons-docs}/repository-namespace-reference.adoc[]
-include::{spring-data-commons-docs}/repository-populator-namespace-reference.adoc[]
-include::{spring-data-commons-docs}/repository-query-keywords-reference.adoc[]
-include::{spring-data-commons-docs}/repository-query-return-types-reference.adoc[]
-:leveloffset: -1
--- a/src/main/asciidoc/preface.adoc
+++ b/src/main/asciidoc/preface.adoc
@@ -1,18 +0,0 @@
-[[couchbase.preface]]
-= Preface
-
-This reference documentation describes the general usage of the Spring Data Couchbase library.
-
-[[metadata]]
-[preface]
-== Project Information
-
-* Version control - https://github.com/spring-projects/spring-data-couchbase
-* Bugtracker - https://github.com/spring-projects/spring-data-couchbase/issues
-* Release repository - https://repo1.maven.org/maven2
-* Milestone repository - https://repo.spring.io/milestone
-* Snapshot repository - https://repo.spring.io/snapshot
-
-[preface]
-include::migrating.adoc[leveloffset=+1]
-
				`@@ -0,0 +1 @@`
				`include::{commons}@data-commons::page$upgrade.adoc[]`
				`@@ -0,0 +1 @@`
				`include::{commons}@data-commons::page$repositories/core-domain-events.adoc[]`