Migrate documentation to Antora.

Closes #1815

Author: mp911de

.gitignore

@@ -7,3 +7,9 @@ target/
 
 *.iml
 .idea
+
+build/
+node_modules
+node
+package.json
+package-lock.json

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 [email protected].
+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 [email protected].
 
 == 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
 

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>

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)

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-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

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/

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]

src/main/asciidoc/migrating.adoc renamed to 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.

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/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.