From 8f8600727c110dff6413dd1b99071623db2b50bd Mon Sep 17 00:00:00 2001 From: Mark Paluch Date: Wed, 31 Jul 2024 14:53:15 +0200 Subject: [PATCH] Bundle Javadoc with Antora documentation site. Closes #2948. --- .gitignore | 1 - package.json | 10 ++++++++++ pom.xml | 2 +- src/main/antora/antora-playbook.yml | 8 +++----- src/main/antora/antora.yml | 5 +++++ src/main/antora/modules/ROOT/nav.adoc | 3 ++- .../ROOT/pages/elasticsearch/clients.adoc | 16 ++++++++-------- .../ROOT/pages/elasticsearch/template.adoc | 8 ++++---- .../junit/jupiter/ClusterConnection.java | 11 +---------- 9 files changed, 34 insertions(+), 30 deletions(-) create mode 100644 package.json diff --git a/.gitignore b/.gitignore index ea0475e14..e4fe384b0 100644 --- a/.gitignore +++ b/.gitignore @@ -30,7 +30,6 @@ target build/ node_modules node -package.json package-lock.json .mvn/.gradle-enterprise diff --git a/package.json b/package.json new file mode 100644 index 000000000..4689506b3 --- /dev/null +++ b/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/pom.xml b/pom.xml index 2384863dc..9d3a870ab 100644 --- a/pom.xml +++ b/pom.xml @@ -468,7 +468,7 @@ - io.spring.maven.antora + org.antora antora-maven-plugin diff --git a/src/main/antora/antora-playbook.yml b/src/main/antora/antora-playbook.yml index 27404c0c1..5f4f76e06 100644 --- 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-elasticsearch' site: title: Spring Data Elasticsearch @@ -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 index 70364a772..2348fca61 100644 --- a/src/main/antora/antora.yml +++ b/src/main/antora/antora.yml @@ -10,3 +10,8 @@ ext: local: true scan: dir: 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 index 04b27c63b..9bd1c8411 100644 --- a/src/main/antora/modules/ROOT/nav.adoc +++ b/src/main/antora/modules/ROOT/nav.adoc @@ -41,4 +41,5 @@ ** xref:repositories/query-keywords-reference.adoc[] ** xref:repositories/query-return-types-reference.adoc[] -* https://github.com/spring-projects/spring-data-commons/wiki[Wiki] +* 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/elasticsearch/clients.adoc b/src/main/antora/modules/ROOT/pages/elasticsearch/clients.adoc index 0f8d8c102..0cf7d5ea3 100644 --- a/src/main/antora/modules/ROOT/pages/elasticsearch/clients.adoc +++ b/src/main/antora/modules/ROOT/pages/elasticsearch/clients.adoc @@ -31,7 +31,7 @@ public class MyClientConfig extends ElasticsearchConfiguration { <.> for a detailed description of the builder methods see xref:elasticsearch/clients.adoc#elasticsearch.clients.configuration[Client Configuration] ==== -The `ElasticsearchConfiguration` class allows further configuration by overriding for example the `jsonpMapper()` or `transportOptions()` methods. +The javadoc:org.springframework.data.elasticsearch.client.elc.ElasticsearchConfiguration[]] class allows further configuration by overriding for example the `jsonpMapper()` or `transportOptions()` methods. The following beans can then be injected in other Spring components: @@ -52,13 +52,13 @@ RestClient restClient; <.> JsonpMapper jsonpMapper; <.> ---- -<.> an implementation of `ElasticsearchOperations` +<.> an implementation of javadoc:org.springframework.data.elasticsearch.core.ElasticsearchOperations[] <.> the `co.elastic.clients.elasticsearch.ElasticsearchClient` that is used. <.> the low level `RestClient` from the Elasticsearch libraries <.> the `JsonpMapper` user by the Elasticsearch `Transport` ==== -Basically one should just use the `ElasticsearchOperations` to interact with the Elasticsearch cluster. +Basically one should just use the javadoc:org.springframework.data.elasticsearch.core.ElasticsearchOperations[] to interact with the Elasticsearch cluster. When using repositories, this instance is used under the hood as well. [[elasticsearch.clients.reactiverestclient]] @@ -86,7 +86,7 @@ public class MyClientConfig extends ReactiveElasticsearchConfiguration { <.> for a detailed description of the builder methods see xref:elasticsearch/clients.adoc#elasticsearch.clients.configuration[Client Configuration] ==== -The `ReactiveElasticsearchConfiguration` class allows further configuration by overriding for example the `jsonpMapper()` or `transportOptions()` methods. +The javadoc:org.springframework.data.elasticsearch.client.elc.ReactiveElasticsearchConfiguration[] class allows further configuration by overriding for example the `jsonpMapper()` or `transportOptions()` methods. The following beans can then be injected in other Spring components: @@ -108,20 +108,20 @@ JsonpMapper jsonpMapper; <.> the following can be injected: -<.> an implementation of `ReactiveElasticsearchOperations` +<.> an implementation of javadoc:org.springframework.data.elasticsearch.core.ReactiveElasticsearchOperations[] <.> the `org.springframework.data.elasticsearch.client.elc.ReactiveElasticsearchClient` that is used. This is a reactive implementation based on the Elasticsearch client implementation. <.> the low level `RestClient` from the Elasticsearch libraries <.> the `JsonpMapper` user by the Elasticsearch `Transport` ==== -Basically one should just use the `ReactiveElasticsearchOperations` to interact with the Elasticsearch cluster. +Basically one should just use the javadoc:org.springframework.data.elasticsearch.core.ReactiveElasticsearchOperations[] to interact with the Elasticsearch cluster. When using repositories, this instance is used under the hood as well. [[elasticsearch.clients.configuration]] == Client Configuration -Client behaviour can be changed via the `ClientConfiguration` that allows to set options for SSL, connect and socket timeouts, headers and other parameters. +Client behaviour can be changed via the javadoc:org.springframework.data.elasticsearch.client.ClientConfiguration[] that allows to set options for SSL, connect and socket timeouts, headers and other parameters. .Client Configuration ==== @@ -178,7 +178,7 @@ If this is used in the reactive setup, the supplier function *must not* block! [[elasticsearch.clients.configuration.callbacks]] === Client configuration callbacks -The `ClientConfiguration` class offers the most common parameters to configure the client. +The javadoc:org.springframework.data.elasticsearch.client.ClientConfiguration[] class offers the most common parameters to configure the client. In the case this is not enough, the user can add callback functions by using the `withClientConfigurer(ClientConfigurationCallback)` method. The following callbacks are provided: diff --git a/src/main/antora/modules/ROOT/pages/elasticsearch/template.adoc b/src/main/antora/modules/ROOT/pages/elasticsearch/template.adoc index b893bb1a1..cf458c3b8 100644 --- a/src/main/antora/modules/ROOT/pages/elasticsearch/template.adoc +++ b/src/main/antora/modules/ROOT/pages/elasticsearch/template.adoc @@ -3,10 +3,10 @@ Spring Data Elasticsearch uses several interfaces to define the operations that can be called against an Elasticsearch index (for a description of the reactive interfaces see xref:elasticsearch/reactive-template.adoc[]). -* `IndexOperations` defines actions on index level like creating or deleting an index. -* `DocumentOperations` defines actions to store, update and retrieve entities based on their id. -* `SearchOperations` define the actions to search for multiple entities using queries -* `ElasticsearchOperations` combines the `DocumentOperations` and `SearchOperations` interfaces. +* javadoc:org.springframework.data.elasticsearch.core.IndexOperations[] defines actions on index level like creating or deleting an index. +* javadoc:org.springframework.data.elasticsearch.core.DocumentOperations[] defines actions to store, update and retrieve entities based on their id. +* javadoc:org.springframework.data.elasticsearch.core.SearchOperations[] define the actions to search for multiple entities using queries +* javadoc:org.springframework.data.elasticsearch.core.ElasticsearchOperations[] combines the `DocumentOperations` and `SearchOperations` interfaces. These interfaces correspond to the structuring of the https://www.elastic.co/guide/en/elasticsearch/reference/current/rest-apis.html[Elasticsearch API]. diff --git a/src/test/java/org/springframework/data/elasticsearch/junit/jupiter/ClusterConnection.java b/src/test/java/org/springframework/data/elasticsearch/junit/jupiter/ClusterConnection.java index 34247bfe9..57badfdd2 100644 --- a/src/test/java/org/springframework/data/elasticsearch/junit/jupiter/ClusterConnection.java +++ b/src/test/java/org/springframework/data/elasticsearch/junit/jupiter/ClusterConnection.java @@ -132,7 +132,7 @@ public class ClusterConnection implements ExtensionContext.Store.CloseableResour DockerImageName dockerImageName = getDockerImageName(testcontainersProperties); ElasticsearchContainer elasticsearchContainer = new SpringDataElasticsearchContainer(dockerImageName) - .withEnv(testcontainersProperties).withStartupTimeout(Duration.ofMinutes(2)); + .withEnv(testcontainersProperties).withStartupTimeout(Duration.ofMinutes(2)).withReuse(true); elasticsearchContainer.start(); return ClusterConnectionInfo.builder() // @@ -192,16 +192,7 @@ public class ClusterConnection implements ExtensionContext.Store.CloseableResour @Override public void close() { - if (clusterConnectionInfo != null && clusterConnectionInfo.getElasticsearchContainer() != null) { - if (LOGGER.isDebugEnabled()) { - LOGGER.debug("Stopping container"); - } - clusterConnectionInfo.getElasticsearchContainer().stop(); - } - if (LOGGER.isDebugEnabled()) { - LOGGER.debug("closed"); - } } private static class SpringDataElasticsearchContainer extends ElasticsearchContainer {