From 21e11adfe324504e5edd4b63f9a730fffe8ceb82 Mon Sep 17 00:00:00 2001 From: Mark Paluch Date: Wed, 31 Jul 2024 11:17:37 +0200 Subject: [PATCH] Bundle Javadoc with Antora documentation site. Closes #2400 --- .gitignore | 1 - spring-data-rest-distribution/package.json | 10 ++++++++++ spring-data-rest-distribution/pom.xml | 2 +- src/main/antora/antora-playbook.yml | 8 +++----- src/main/antora/antora.yml | 5 +++++ src/main/antora/modules/ROOT/nav.adoc | 3 ++- src/main/antora/modules/ROOT/pages/events.adoc | 16 ++++++++-------- .../antora/modules/ROOT/pages/integration.adoc | 4 ++-- src/main/antora/modules/ROOT/pages/intro.adoc | 2 +- 9 files changed, 32 insertions(+), 19 deletions(-) create mode 100644 spring-data-rest-distribution/package.json diff --git a/.gitignore b/.gitignore index ef40aef30..3796d5264 100644 --- a/.gitignore +++ b/.gitignore @@ -14,6 +14,5 @@ out/ _site node_modules package-lock.json -package.json node .mvn/.gradle-enterprise diff --git a/spring-data-rest-distribution/package.json b/spring-data-rest-distribution/package.json new file mode 100644 index 000000000..4689506b3 --- /dev/null +++ b/spring-data-rest-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-rest-distribution/pom.xml b/spring-data-rest-distribution/pom.xml index 94bebe05d..d2ce28315 100644 --- a/spring-data-rest-distribution/pom.xml +++ b/spring-data-rest-distribution/pom.xml @@ -49,7 +49,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 4fa8c6053..73a57d304 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-rest' site: title: Spring Data REST @@ -17,13 +16,12 @@ content: worktrees: true 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: '' @@ -33,5 +31,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 c7f815e22..f8fb61f77 100644 --- a/src/main/antora/antora.yml +++ b/src/main/antora/antora.yml @@ -10,3 +10,8 @@ ext: local: true scan: dir: spring-data-rest-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 index 8d89de62c..366c6aab9 100644 --- a/src/main/antora/modules/ROOT/nav.adoc +++ b/src/main/antora/modules/ROOT/nav.adoc @@ -27,4 +27,5 @@ ** xref:customizing/custom-jackson-deserialization.adoc[] ** xref:customizing/configuring-cors.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/events.adoc b/src/main/antora/modules/ROOT/pages/events.adoc index 98b5a877a..b98753be1 100644 --- a/src/main/antora/modules/ROOT/pages/events.adoc +++ b/src/main/antora/modules/ROOT/pages/events.adoc @@ -3,14 +3,14 @@ The REST exporter emits eight different events throughout the process of working with an entity: -* `BeforeCreateEvent` -* `AfterCreateEvent` -* `BeforeSaveEvent` -* `AfterSaveEvent` -* `BeforeLinkSaveEvent` -* `AfterLinkSaveEvent` -* `BeforeDeleteEvent` -* `AfterDeleteEvent` +* javadoc:org.springframework.data.rest.core.event.BeforeCreateEvent[] +* javadoc:org.springframework.data.rest.core.event.AfterCreateEvent[] +* javadoc:org.springframework.data.rest.core.event.BeforeSaveEvent[] +* javadoc:org.springframework.data.rest.core.event.AfterSaveEvent[] +* javadoc:org.springframework.data.rest.core.event.BeforeLinkSaveEvent[] +* javadoc:org.springframework.data.rest.core.event.AfterLinkSaveEvent[] +* javadoc:org.springframework.data.rest.core.event.BeforeDeleteEvent[] +* javadoc:org.springframework.data.rest.core.event.AfterDeleteEvent[] [[events.application-listener]] == Writing an `ApplicationListener` diff --git a/src/main/antora/modules/ROOT/pages/integration.adoc b/src/main/antora/modules/ROOT/pages/integration.adoc index ac04cb33c..accd11165 100644 --- a/src/main/antora/modules/ROOT/pages/integration.adoc +++ b/src/main/antora/modules/ROOT/pages/integration.adoc @@ -10,7 +10,7 @@ Sometimes you need to add links to exported resources in your own custom-built S * Manually assembling links. * Using Spring HATEOAS's https://docs.spring.io/spring-hateoas/docs/current/reference/html/#fundamentals.obtaining-links.builder[`LinkBuilder`] with `linkTo()`, `slash()`, and so on. -* Using Spring Data REST's implementation of https://docs.spring.io/spring-data/rest/docs/current/api/org/springframework/data/rest/webmvc/support/RepositoryEntityLinks.html[`RepositoryEntityLinks`]. +* Using Spring Data REST's implementation of javadoc:org.springframework.data.rest.webmvc.support.RepositoryEntityLinks[]. The first suggestion is terrible and should be avoided at all costs. It makes your code brittle and high-risk. The second is handy when creating links to other hand-written Spring MVC controllers. The last one, which we explore in the rest of this section, is good for looking up resource links that are exported by Spring Data REST. @@ -54,4 +54,4 @@ With the class in the preceding example, you can use the following operations: |=== -NOTE: All of the search-based links support extra parameters for paging and sorting. See https://docs.spring.io/spring-data/rest/docs/current/api/org/springframework/data/rest/webmvc/support/RepositoryEntityLinks.html[`RepositoryEntityLinks`] for the details. There is also `linkFor(Class type)`, but that returns a Spring HATEOAS `LinkBuilder`, which returns you to the lower level API. Try to use the other ones first. +NOTE: All of the search-based links support extra parameters for paging and sorting. See javadoc:org.springframework.data.rest.webmvc.support.RepositoryEntityLinks[] for the details. There is also `linkFor(Class type)`, but that returns a Spring HATEOAS `LinkBuilder`, which returns you to the lower level API. Try to use the other ones first. diff --git a/src/main/antora/modules/ROOT/pages/intro.adoc b/src/main/antora/modules/ROOT/pages/intro.adoc index 8e5c61f4f..d8a53d909 100644 --- a/src/main/antora/modules/ROOT/pages/intro.adoc +++ b/src/main/antora/modules/ROOT/pages/intro.adoc @@ -2,6 +2,6 @@ = Introduction :page-section-summary-toc: 1 -REST web services have become the number one means for application integration on the web. In its core, REST defines that a system that consists of resources with which clients interact. These resources are implemented in a hypermedia-driven way. link:{springDocsUrl}/web.html#spring-web[Spring MVC] and link:{springDocsUrl}/web-reactive.html#spring-webflux[Spring WebFlux] each offer a solid foundation to build theses kinds of services. However, implementing even the simplest tenet of REST web services for a multi-domain object system can be quite tedious and result in a lot of boilerplate code. +REST web services have become the number one means for application integration on the web. In its core, REST defines that a system that consists of resources with which clients interact. These resources are implemented in a hypermedia-driven way. link:{springDocsUrl}/web.html#spring-web[Spring MVC] and link:{springDocsUrl}/web-reactive.html#spring-webflux[Spring WebFlux] each offer a solid foundation to build these kinds of services. However, implementing even the simplest tenet of REST web services for a multi-domain object system can be quite tedious and result in a lot of boilerplate code. Spring Data REST builds on top of the Spring Data repositories and automatically exports those as REST resources. It leverages hypermedia to let clients automatically find functionality exposed by the repositories and integrate these resources into related hypermedia-based functionality.