Bundle Javadoc with Antora documentation site.

mp911de · mp911de · commit 7c81b2c83f95 · 2024-07-31T10:46:15.000+02:00
Closes #4754
diff --git a/.gitignore b/.gitignore
@@ -19,6 +19,5 @@ atlassian-ide-plugin.xml
 build/
 node_modules
 node
-package.json
 package-lock.json
 .mvn/.gradle-enterprise
diff --git a/spring-data-mongodb-distribution/package.json b/spring-data-mongodb-distribution/package.json
@@ -0,0 +1,10 @@
+{
+    "dependencies": {
+        "antora": "3.2.0-alpha.6",
+        "@antora/atlas-extension": "1.0.0-alpha.2",
+        "@antora/collector-extension": "1.0.0-alpha.7",
+        "@asciidoctor/tabs": "1.0.0-beta.6",
+        "@springio/antora-extensions": "1.13.0",
+        "@springio/asciidoctor-extensions": "1.0.0-alpha.11"
+    }
+}
diff --git a/spring-data-mongodb-distribution/pom.xml b/spring-data-mongodb-distribution/pom.xml
@@ -66,7 +66,7 @@
 				<artifactId>maven-assembly-plugin</artifactId>
 			</plugin>
 			<plugin>
-				<groupId>io.spring.maven.antora</groupId>
+				<groupId>org.antora</groupId>
 				<artifactId>antora-maven-plugin</artifactId>
 			</plugin>
 		</plugins>
diff --git a/src/main/antora/antora-playbook.yml b/src/main/antora/antora-playbook.yml
@@ -3,8 +3,7 @@
 # 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'
+    - require: '@springio/antora-extensions'
       root_component_name: 'data-mongodb'
 site:
   title: Spring Data MongoDB
@@ -22,13 +21,12 @@ content:
       start_path: src/main/antora
 asciidoc:
   attributes:
-    page-pagination: ''
     hide-uri-scheme: '@'
     tabs-sync-option: '@'
-    chomp: 'all'
   extensions:
     - '@asciidoctor/tabs'
     - '@springio/asciidoctor-extensions'
+    - '@springio/asciidoctor-extensions/javadoc-extension'
   sourcemap: true
 urls:
   latest_version_segment: ''
@@ -38,5 +36,5 @@ runtime:
     format: pretty
 ui:
   bundle:
-    url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.3.5/ui-bundle.zip
+    url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.4.16/ui-bundle.zip
     snapshot: true
diff --git a/src/main/antora/antora.yml b/src/main/antora/antora.yml
@@ -10,3 +10,8 @@ ext:
         local: true
       scan:
         dir: spring-data-mongodb-distribution/target/classes/
+    - run:
+        command: ./mvnw package -Pdistribute
+        local: true
+      scan:
+        dir: target/antora
diff --git a/src/main/antora/modules/ROOT/nav.adoc b/src/main/antora/modules/ROOT/nav.adoc
@@ -64,3 +64,6 @@
 ** xref:kotlin/extensions.adoc[]
 ** xref:kotlin/coroutines.adoc[]
 
+* xref:attachment$api/java/index.html[Javadoc,role=link-external,window=_blank]
+* https://github.com/spring-projects/spring-data-commons/wiki[Wiki,role=link-external,window=_blank]
+
diff --git a/src/main/antora/modules/ROOT/pages/mongodb/aggregation-framework.adoc b/src/main/antora/modules/ROOT/pages/mongodb/aggregation-framework.adoc
@@ -8,7 +8,7 @@ For further information, see the full https://docs.mongodb.org/manual/aggregatio
 [[mongo.aggregation.basic-concepts]]
 == Basic Concepts
 
-The Aggregation Framework support in Spring Data MongoDB is based on the following key abstractions: `Aggregation`, `AggregationDefinition`, and `AggregationResults`.
+The Aggregation Framework support in Spring Data MongoDB is based on the following key abstractions: javadoc:org.springframework.data.mongodb.core.aggregation.Aggregation[] and javadoc:org.springframework.data.mongodb.core.aggregation.AggregationResults[].
 
 * `Aggregation`
 +
diff --git a/src/main/antora/modules/ROOT/pages/mongodb/change-streams.adoc b/src/main/antora/modules/ROOT/pages/mongodb/change-streams.adoc
@@ -16,8 +16,8 @@ In doubt, use `Document`.
 == Change Streams with `MessageListener`
 
 Listening to a https://docs.mongodb.com/manual/tutorial/change-streams-example/[Change Stream by using a Sync Driver] creates a long running, blocking task that needs to be delegated to a separate component.
-In this case, we need to first create a `MessageListenerContainer`, which will be the main entry point for running the specific `SubscriptionRequest` tasks.
-Spring Data MongoDB already ships with a default implementation that operates on `MongoTemplate` and is capable of creating and running `Task` instances for a `ChangeStreamRequest`.
+In this case, we need to first create a javadoc:org.springframework.data.mongodb.core.messaging.MessageListenerContainer[] which will be the main entry point for running the specific `SubscriptionRequest` tasks.
+Spring Data MongoDB already ships with a default implementation that operates on `MongoTemplate` and is capable of creating and running `Task` instances for a javadoc:org.springframework.data.mongodb.core.messaging.ChangeStreamRequest[].
 
 The following example shows how to use Change Streams with `MessageListener` instances:
 
@@ -73,7 +73,7 @@ Flux<ChangeStreamEvent<User>> flux = reactiveTemplate.changeStream(User.class) <
 == Resuming Change Streams
 
 Change Streams can be resumed and resume emitting events where you left. To resume the stream, you need to supply either a resume
-token or the last known server time (in UTC). Use `ChangeStreamOptions` to set the value accordingly.
+token or the last known server time (in UTC). Use javadoc:org.springframework.data.mongodb.core.ChangeStreamOptions[] to set the value accordingly.
 
 The following example shows how to set the resume offset using server time:
 
diff --git a/src/main/antora/modules/ROOT/pages/mongodb/getting-started.adoc b/src/main/antora/modules/ROOT/pages/mongodb/getting-started.adoc
@@ -55,7 +55,7 @@ Person [id=4ddbba3c0be56b7e1b210166, name=Joe, age=34]
 Even in this simple example, there are few things to notice:
 
 * You can instantiate the central helper class of Spring Mongo, xref:mongodb/template-api.adoc[`MongoTemplate`], by using the standard or reactive `MongoClient` object and the name of the database to use.
-* The mapper works against standard POJO objects without the need for any additional metadata (though you can optionally provide that information. See xref:mongodb/mapping/mapping.adoc[here].).
+* The mapper works against standard POJO objects without the need for any additional metadata (though you can optionally provide that information. See xref:mongodb/mapping/mapping.adoc[here]).
 * Conventions are used for handling the `id` field, converting it to be an `ObjectId` when stored in the database.
 * Mapping conventions can use field access. Notice that the `Person` class has only getters.
 * If the constructor argument names match the field names of the stored document, they are used to instantiate the object
diff --git a/src/main/antora/modules/ROOT/pages/mongodb/lifecycle-events.adoc b/src/main/antora/modules/ROOT/pages/mongodb/lifecycle-events.adoc
@@ -5,7 +5,7 @@ The MongoDB mapping framework includes several `org.springframework.context.Appl
 Being based on Spring's `ApplicationContext` event infrastructure enables other products, such as Spring Integration, to easily receive these events, as they are a well known eventing mechanism in Spring-based applications.
 
 Entity lifecycle events can be costly and you may notice a change in the performance profile when loading large result sets.
-You can disable lifecycle events on the link:https://docs.spring.io/spring-data/mongodb/docs/{version}/api/org/springframework/data/mongodb/core/MongoTemplate.html#setEntityLifecycleEventsEnabled(boolean)[Template API].
+You can disable lifecycle events on the javadoc:org.springframework.data.mongodb.core.MongoTemplate#setEntityLifecycleEventsEnabled(boolean)[Template API].
 
 To intercept an object before it goes through the conversion process (which turns your domain object into a `org.bson.Document`), you can register a subclass of `AbstractMongoEventListener` that overrides the `onBeforeConvert` method.
 When the event is dispatched, your listener is called and passed the domain object before it goes into the converter.
@@ -23,7 +23,7 @@ public class BeforeConvertListener extends AbstractMongoEventListener<Person> {
 ----
 ====
 
-To intercept an object before it goes into the database, you can register a subclass of `org.springframework.data.mongodb.core.mapping.event.AbstractMongoEventListener` that overrides the `onBeforeSave` method. When the event is dispatched, your listener is called and passed the domain object and the converted `com.mongodb.Document`. The following example shows how to do so:
+To intercept an object before it goes into the database, you can register a subclass of javadoc:org.springframework.data.mongodb.core.mapping.event.AbstractMongoEventListener[] that overrides the `onBeforeSave` method. When the event is dispatched, your listener is called and passed the domain object and the converted `com.mongodb.Document`. The following example shows how to do so:
 
 ====
 [source,java]
diff --git a/src/main/antora/modules/ROOT/pages/mongodb/template-api.adoc b/src/main/antora/modules/ROOT/pages/mongodb/template-api.adoc
@@ -1,22 +1,22 @@
 [[mongo-template]]
 = Template API
 
-The `MongoTemplate` and its reactive counterpart class, located in the `org.springframework.data.mongodb.core` package, is the central class of Spring's MongoDB support and provides a rich feature set for interacting with the database.
+The javadoc:org.springframework.data.mongodb.core.MongoTemplate[] and its javadoc:org.springframework.data.mongodb.core.ReactiveMongoTemplate[reactive] counterpart class, located in the `org.springframework.data.mongodb.core` package, is the central class of Spring's MongoDB support and provides a rich feature set for interacting with the database.
 The template offers convenience operations to create, update, delete, and query MongoDB documents and provides a mapping between your domain objects and MongoDB documents.
 
 NOTE: Once configured, `MongoTemplate` is thread-safe and can be reused across multiple instances.
 
 [[mongo-template.convenience-methods]]
 == Convenience Methods
 
-The `MongoTemplate` class implements the interface `MongoOperations`.
+The javadoc:org.springframework.data.mongodb.core.MongoTemplate[] class implements the interface javadoc:org.springframework.data.mongodb.core.MongoOperations[].
 In as much as possible, the methods on `MongoOperations` are named after methods available on the MongoDB driver `Collection` object, to make the API familiar to existing MongoDB developers who are used to the driver API.
 For example, you can find methods such as `find`, `findAndModify`, `findAndReplace`, `findOne`, `insert`, `remove`, `save`, `update`, and `updateMulti`.
 The design goal was to make it as easy as possible to transition between the use of the base MongoDB driver and `MongoOperations`.
 A major difference between the two APIs is that `MongoOperations` can be passed domain objects instead of `Document`.
 Also, `MongoOperations` has fluent APIs for `Query`, `Criteria`, and `Update` operations instead of populating a `Document` to specify the parameters for those operations.
 
-For more information please refer to the the xref:mongodb/template-crud-operations.adoc[CRUD] and xref:mongodb/template-query-operations.adoc[Query] sections of the documentation.
+For more information please refer to the xref:mongodb/template-crud-operations.adoc[CRUD] and xref:mongodb/template-query-operations.adoc[Query] sections of the documentation.
 
 NOTE: The preferred way to reference the operations on `MongoTemplate` instance is through its interface, `MongoOperations`.
 
@@ -37,7 +37,7 @@ The `execute` callbacks gives you a reference to either a `MongoCollection` or a
 
 * `<T> T` *executeInSession* `(DbCallback<T> action)`: Runs the given `DbCallback` within the same connection to the database so as to ensure consistency in a write-heavy environment where you may read the data that you wrote.
 
-The following example uses the `CollectionCallback` to return information about an index:
+The following example uses the javadoc:org.springframework.data.mongodb.core.CollectionCallback[] to return information about an index:
 
 [tabs]
 ======
@@ -108,7 +108,7 @@ Flux<Jedi> all = template.query(SWCharacter.class)
 ======
 
 NOTE: Using projections allows `MongoTemplate` to optimize result mapping by limiting the actual response to fields required
-by the projection target type. This applies as long as the `Query` itself does not contain any field restriction and the
+by the projection target type. This applies as long as the javadoc:org.springframework.data.mongodb.core.query.Query[] itself does not contain any field restriction and the
 target type is a closed interface or DTO projection.
 
 WARNING: Projections must not be applied to xref:mongodb/mapping/document-references.adoc[DBRefs].
@@ -158,7 +158,7 @@ Look into the implementation for more details on the mapping.
 [[mongo-template.type-mapping]]
 == Domain Type Mapping
 
-The mapping between MongoDB documents and domain classes is done by delegating to an implementation of the `MongoConverter` interface.
-Spring provides `MappingMongoConverter`, but you can also write your own converter.
+The mapping between MongoDB documents and domain classes is done by delegating to an implementation of the javadoc:org.springframework.data.mongodb.core.convert.MongoConverter[] interface.
+Spring provides javadoc:org.springframework.data.mongodb.core.convert.MappingMongoConverter[], but you can also write your own converter.
 While the `MappingMongoConverter` can use additional metadata to specify the mapping of objects to documents, it can also convert objects that contain no additional metadata by using some conventions for the mapping of IDs and collection names.
 These conventions, as well as the use of mapping annotations, are explained in the xref:mongodb/mapping/mapping.adoc[Mapping] chapter.
diff --git a/src/main/antora/modules/ROOT/pages/mongodb/template-config.adoc b/src/main/antora/modules/ROOT/pages/mongodb/template-config.adoc
@@ -57,7 +57,7 @@ XML::
 ----
 ======
 
-There are several overloaded constructors of `MongoTemplate` and `ReactiveMongoTemplate`:
+There are several overloaded constructors of javadoc:org.springframework.data.mongodb.core.MongoTemplate[] and javadoc:org.springframework.data.mongodb.core.ReactiveMongoTemplate[]:
 
 * `MongoTemplate(MongoClient mongo, String databaseName)`: Takes the `MongoClient` object and the default database name to operate against.
 * `MongoTemplate(MongoDatabaseFactory mongoDbFactory)`: Takes a MongoDbFactory object that encapsulated the `MongoClient` object, database name, and username and password.
@@ -164,4 +164,4 @@ ReactiveMongoOperations mongoTemplate(MongoClient mongoClient) {
 == Document count configuration
 
 By setting `MongoTemplate#useEstimatedCount(...)` to `true` _MongoTemplate#count(...)_ operations, that use an empty filter query, will be delegated to `estimatedCount`, as long as there is no transaction active and the template is not bound to a xref:mongodb/client-session-transactions.adoc[session].
-Please refer to to the xref:mongodb/template-document-count.adoc#mongo.query.count[Counting Documents] section for more information.
+Please refer to the xref:mongodb/template-document-count.adoc#mongo.query.count[Counting Documents] section for more information.
diff --git a/src/main/antora/modules/ROOT/pages/mongodb/template-gridfs.adoc b/src/main/antora/modules/ROOT/pages/mongodb/template-gridfs.adoc
@@ -2,7 +2,7 @@
 = GridFS Support
 
 MongoDB supports storing binary files inside its filesystem, GridFS.
-Spring Data MongoDB provides a `GridFsOperations` and `ReactiveGridFsOperations` interface as well as the corresponding implementation, `GridFsTemplate` and `ReactiveGridFsTemplate`, to let you interact with the filesystem.
+Spring Data MongoDB provides a javadoc:org.springframework.data.mongodb.gridfs.GridFsOperations[] and javadoc:org.springframework.data.mongodb.gridfs.ReactiveGridFsOperations[] interface as well as the corresponding implementation, `GridFsTemplate` and `ReactiveGridFsTemplate`, to let you interact with the filesystem.
 You can set up a template instance by handing it a `MongoDatabaseFactory`/`ReactiveMongoDatabaseFactory` as well as a `MongoConverter`, as the following example shows:
 
 [tabs]
diff --git a/src/main/antora/modules/ROOT/pages/mongodb/template-query-operations.adoc b/src/main/antora/modules/ROOT/pages/mongodb/template-query-operations.adoc
@@ -472,7 +472,7 @@ The `Metrics` enum used here actually implements an interface so that other metr
 A `Metric` is backed by a multiplier to transform the distance value of the given metric into native distances.
 The sample shown here would consider the 10 to be miles. Using one of the built-in metrics (miles and kilometers) automatically triggers the spherical flag to be set on the query.
 If you want to avoid that, pass plain `double` values into `maxDistance(…)`.
-For more information, see the https://docs.spring.io/spring-data/mongodb/docs/{version}/api/index.html[JavaDoc] of `NearQuery` and `Distance`.
+For more information, see the Javadoc of javadoc:org.springframework.data.mongodb.core.query.NearQuery[] and `Distance`.
 
 The geo-near operations return a `GeoResults` wrapper object that encapsulates `GeoResult` instances.
 Wrapping `GeoResults` allows accessing the average distance of all results.
@@ -486,7 +486,7 @@ MongoDB supports https://geojson.org/[GeoJSON] and simple (legacy) coordinate pa
 [[mongo.geo-json.domain.classes]]
 == GeoJSON Types in Domain Classes
 
-Usage of https://geojson.org/[GeoJSON] types in domain classes is straightforward. The `org.springframework.data.mongodb.core.geo` package contains types such as `GeoJsonPoint`, `GeoJsonPolygon`, and others. These types are extend the existing `org.springframework.data.geo` types. The following example uses a `GeoJsonPoint`:
+Usage of https://geojson.org/[GeoJSON] types in domain classes is straightforward. The `org.springframework.data.mongodb.core.geo` package contains types such as `GeoJsonPoint`, `GeoJsonPolygon`, and others. These types are extend the existing `org.springframework.data.geo` types. The following example uses a javadoc:org.springframework.data.mongodb.core.geo.GeoJsonPoint[]:
 
 ====
 [source,java]

Original file line number	Diff line number	Diff line change
`@@ -8,7 +8,7 @@ For further information, see the full https://docs.mongodb.org/manual/aggregatio`
`8`	`8`	`[[mongo.aggregation.basic-concepts]]`
`9`	`9`	`== Basic Concepts`
`10`	`10`
`11`		-The Aggregation Framework support in Spring Data MongoDB is based on the following key abstractions: `Aggregation`, `AggregationDefinition`, and `AggregationResults`.
	`11`	`+The Aggregation Framework support in Spring Data MongoDB is based on the following key abstractions: javadoc:org.springframework.data.mongodb.core.aggregation.Aggregation[] and javadoc:org.springframework.data.mongodb.core.aggregation.AggregationResults[].`
`12`	`12`
`13`	`13`	* `Aggregation`
`14`	`14`	`+`