From 59b73c40403b803508387dbecbb76e44d8dfbca8 Mon Sep 17 00:00:00 2001 From: Olga MaciaszekSharma Date: Fri, 15 Sep 2023 18:49:12 +0200 Subject: [PATCH] Build Antora docs. --- .../workflows/deploy-docs.yml | 0 .gitignore | 6 ++ docs/antora-playbook.yml | 11 +--- docs/antora.yml | 4 +- docs/modules/ROOT/nav.adoc | 10 +--- docs/modules/ROOT/pages/_configprops.adoc | 37 ------------ docs/modules/ROOT/pages/appendix.adoc | 2 +- docs/modules/ROOT/pages/configprops.adoc | 6 ++ docs/modules/ROOT/pages/index.adoc | 9 +++ docs/modules/ROOT/pages/intro.adoc | 3 + .../ROOT/pages/spring-cloud-openfeign.adoc | 10 +--- docs/modules/ROOT/partials/_attributes.adoc | 3 + docs/pom.xml | 60 +++++++++++++++---- .../resources/antora-resources/antora.yml | 20 +++++++ .../pages => src/main/asciidoc}/README.adoc | 0 .../main/asciidoc}/sagan-boot.adoc | 0 .../main/asciidoc}/sagan-index.adoc | 0 17 files changed, 109 insertions(+), 72 deletions(-) rename {docs/.github => .github}/workflows/deploy-docs.yml (100%) delete mode 100644 docs/modules/ROOT/pages/_configprops.adoc create mode 100644 docs/modules/ROOT/pages/configprops.adoc create mode 100644 docs/modules/ROOT/partials/_attributes.adoc create mode 100644 docs/src/main/antora/resources/antora-resources/antora.yml rename docs/{modules/ROOT/pages => src/main/asciidoc}/README.adoc (100%) rename docs/{modules/ROOT/pages => src/main/asciidoc}/sagan-boot.adoc (100%) rename docs/{modules/ROOT/pages => src/main/asciidoc}/sagan-index.adoc (100%) diff --git a/docs/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml similarity index 100% rename from docs/.github/workflows/deploy-docs.yml rename to .github/workflows/deploy-docs.yml diff --git a/.gitignore b/.gitignore index 8a860b40..388132e8 100644 --- a/.gitignore +++ b/.gitignore @@ -21,3 +21,9 @@ _site/ .vscode/ .flattened-pom.xml + +node +node_modules +build +package.json +package-lock.json diff --git a/docs/antora-playbook.yml b/docs/antora-playbook.yml index 9a70e676..6cd8d672 100644 --- a/docs/antora-playbook.yml +++ b/docs/antora-playbook.yml @@ -6,15 +6,10 @@ antora: - '@antora/collector-extension' - '@antora/atlas-extension' - require: '@springio/antora-extensions/root-component-extension' - root_component_name: 'PROJECT_WITHOUT_SPRING' - # FIXME: Run antora once using this extension to migrate to the Asciidoc Tabs syntax - # and then remove this extension - - require: '@springio/antora-extensions/tabs-migration-extension' - unwrap_example_block: always - save_result: true + root_component_name: 'cloud-openfeign' site: - title: PROJECT_FULL_NAME - url: https://docs.spring.io/PROJECT_NAME/reference/ + title: Spring Cloud Openfeign + url: https://docs.spring.io/spring-cloud-openfeign/reference/ content: sources: - url: ./.. diff --git a/docs/antora.yml b/docs/antora.yml index 15b346da..dc2b1a7d 100644 --- a/docs/antora.yml +++ b/docs/antora.yml @@ -1,6 +1,6 @@ -name: PROJECT_WITHOUT_SPRING +name: cloud-openfeign version: true -title: PROJECT_NAME +title: Spring Cloud OpenFeign nav: - modules/ROOT/nav.adoc ext: diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 5d5a53a8..8769f935 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -1,9 +1,5 @@ * xref:index.adoc[] -* xref:spring-cloud-openfeign.adoc[] -* xref:_attributes.adoc[] -* xref:intro.adoc[] -* xref:README.adoc[] -* xref:_configprops.adoc[] +** xref:intro.adoc[] +** xref:spring-cloud-openfeign.adoc[] * xref:appendix.adoc[] -* xref:sagan-boot.adoc[] -* xref:sagan-index.adoc[] +** xref:configprops.adoc[] diff --git a/docs/modules/ROOT/pages/_configprops.adoc b/docs/modules/ROOT/pages/_configprops.adoc deleted file mode 100644 index 6d8de12a..00000000 --- a/docs/modules/ROOT/pages/_configprops.adoc +++ /dev/null @@ -1,37 +0,0 @@ -|=== -|Name | Default | Description - -|spring.cloud.openfeign.autoconfiguration.jackson.enabled | `false` | If true, PageJacksonModule and SortJacksonModule bean will be provided for Jackson page decoding. -|spring.cloud.openfeign.circuitbreaker.enabled | `false` | If true, an OpenFeign client will be wrapped with a Spring Cloud CircuitBreaker circuit breaker. -|spring.cloud.openfeign.circuitbreaker.group.enabled | `false` | If true, an OpenFeign client will be wrapped with a Spring Cloud CircuitBreaker circuit breaker with with group. -|spring.cloud.openfeign.client.config | | -|spring.cloud.openfeign.client.decode-slash | `true` | Feign clients do not encode slash `/` characters by default. To change this behavior, set the `decodeSlash` to `false`. -|spring.cloud.openfeign.client.default-config | `default` | -|spring.cloud.openfeign.client.default-to-properties | `true` | -|spring.cloud.openfeign.client.refresh-enabled | `false` | Enables options value refresh capability for Feign. -|spring.cloud.openfeign.compression.request.enabled | `false` | Enables the request sent by Feign to be compressed. -|spring.cloud.openfeign.compression.request.mime-types | `[text/xml, application/xml, application/json]` | The list of supported mime types. -|spring.cloud.openfeign.compression.request.min-request-size | `2048` | The minimum threshold content size. -|spring.cloud.openfeign.compression.response.enabled | `false` | Enables the response from Feign to be compressed. -|spring.cloud.openfeign.encoder.charset-from-content-type | `false` | Indicates whether the charset should be derived from the {@code Content-Type} header. -|spring.cloud.openfeign.httpclient.connection-timeout | `2000` | -|spring.cloud.openfeign.httpclient.connection-timer-repeat | `3000` | -|spring.cloud.openfeign.httpclient.disable-ssl-validation | `false` | -|spring.cloud.openfeign.httpclient.enabled | `true` | Enables the use of the Apache HTTP Client by Feign. -|spring.cloud.openfeign.httpclient.follow-redirects | `true` | -|spring.cloud.openfeign.httpclient.hc5.enabled | `false` | Enables the use of the Apache HTTP Client 5 by Feign. -|spring.cloud.openfeign.httpclient.hc5.pool-concurrency-policy | | Pool concurrency policies. -|spring.cloud.openfeign.httpclient.hc5.pool-reuse-policy | | Pool connection re-use policies. -|spring.cloud.openfeign.httpclient.hc5.socket-timeout | `5` | Default value for socket timeout. -|spring.cloud.openfeign.httpclient.hc5.socket-timeout-unit | | Default value for socket timeout unit. -|spring.cloud.openfeign.httpclient.max-connections | `200` | -|spring.cloud.openfeign.httpclient.max-connections-per-route | `50` | -|spring.cloud.openfeign.httpclient.ok-http.read-timeout | `60s` | {@link OkHttpClient} read timeout; defaults to 60 seconds. -|spring.cloud.openfeign.httpclient.time-to-live | `900` | -|spring.cloud.openfeign.httpclient.time-to-live-unit | | -|spring.cloud.openfeign.micrometer.enabled | `true` | Enables Micrometer capabilities for Feign. -|spring.cloud.openfeign.oauth2.enabled | `false` | Enables feign interceptor for managing oauth2 access token. -|spring.cloud.openfeign.oauth2.load-balanced | `false` | Enables load balancing for oauth2 access token provider. -|spring.cloud.openfeign.okhttp.enabled | `false` | Enables the use of the OK HTTP Client by Feign. - -|=== diff --git a/docs/modules/ROOT/pages/appendix.adoc b/docs/modules/ROOT/pages/appendix.adoc index eef1c905..439fb791 100644 --- a/docs/modules/ROOT/pages/appendix.adoc +++ b/docs/modules/ROOT/pages/appendix.adoc @@ -6,7 +6,7 @@ Various properties can be specified inside your `application.properties` file, inside your `application.yml` file, or as command line switches. -This appendix provides a list of common {project-full-name} properties and references to the underlying classes that consume them. +This appendix provides a list of common Spring Cloud OpenFeign properties and references to the underlying classes that consume them. NOTE: Property contributions can come from additional jar files on your classpath, so you should not consider this an exhaustive list. Also, you can define your own properties. diff --git a/docs/modules/ROOT/pages/configprops.adoc b/docs/modules/ROOT/pages/configprops.adoc new file mode 100644 index 00000000..32cbb8e5 --- /dev/null +++ b/docs/modules/ROOT/pages/configprops.adoc @@ -0,0 +1,6 @@ +[[configuration-properties]] += Configuration Properties + +Below you can find a list of configuration properties. + +include::partial$_configprops.adoc[] diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index e69de29b..69cf1101 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -0,0 +1,9 @@ +[[cloud-native-applications]] += Cloud Native Applications + +include::partial$_attributes.adoc[] + +// TODO: figure out remote includes in docs and replace pasted text +// include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/contributing-docs.adoc[] +NOTE: Spring Cloud is released under the non-restrictive Apache 2.0 license. +If you would like to contribute to this section of the documentation or if you find an error, you can find the source code and issue trackers for the project at {github-issues}[github]. diff --git a/docs/modules/ROOT/pages/intro.adoc b/docs/modules/ROOT/pages/intro.adoc index a69a78c5..d837d0eb 100644 --- a/docs/modules/ROOT/pages/intro.adoc +++ b/docs/modules/ROOT/pages/intro.adoc @@ -1,3 +1,6 @@ +[[intro]] += Introduction + This project provides OpenFeign integrations for Spring Boot apps through autoconfiguration and binding to the Spring Environment and other Spring programming model idioms. diff --git a/docs/modules/ROOT/pages/spring-cloud-openfeign.adoc b/docs/modules/ROOT/pages/spring-cloud-openfeign.adoc index 28ffc708..0395700a 100644 --- a/docs/modules/ROOT/pages/spring-cloud-openfeign.adoc +++ b/docs/modules/ROOT/pages/spring-cloud-openfeign.adoc @@ -1,9 +1,5 @@ -[[spring-cloud-openfeign]] -= Spring Cloud OpenFeign - -*{spring-cloud-version}* - - +[[features]] += Spring Cloud OpenFeign Features [[spring-cloud-feign]] == Declarative REST Client: Feign @@ -846,7 +842,7 @@ If Feign client refresh is enabled, each Feign client is created with: * `feign.Request.Options` as a refresh-scoped bean. This means properties such as `connectTimeout` and `readTimeout` can be refreshed against any Feign client instance. * A url wrapped under `org.springframework.cloud.openfeign.RefreshableUrl`. This means the URL of Feign client, if defined -with `spring.cloud.openfeign.client.config.{feignName}.url` property, can be refreshed against any Feign client instance. +with `spring.cloud.openfeign.client.config.\{feignName}.url` property, can be refreshed against any Feign client instance. You can refresh these properties through `POST /actuator/refresh`. diff --git a/docs/modules/ROOT/partials/_attributes.adoc b/docs/modules/ROOT/partials/_attributes.adoc new file mode 100644 index 00000000..959d40f4 --- /dev/null +++ b/docs/modules/ROOT/partials/_attributes.adoc @@ -0,0 +1,3 @@ +:sc-ext: java +:project-full-name: Spring Cloud OpenFeign +:all: {asterisk}{asterisk} diff --git a/docs/pom.xml b/docs/pom.xml index 23974a74..f9565725 100644 --- a/docs/pom.xml +++ b/docs/pom.xml @@ -3,25 +3,32 @@ xmlns="http://maven.apache.org/POM/4.0.0" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> 4.0.0 + org.springframework.cloud + spring-cloud-openfeign-docs org.springframework.cloud spring-cloud-openfeign 4.1.0-SNAPSHOT + .. https://github.com/spring-cloud/spring-cloud-openfeign - spring-cloud-openfeign-docs jar Spring Cloud OpenFeign Docs - Spring Cloud Docs + Spring Cloud OpenFeign Docs spring-cloud-openfeign ${basedir}/.. - feign.* - deploy + spring.cloud.* none + + + 1.0.2 + ${maven.multiModuleProjectDirectory}/ + .* + ${maven.multiModuleProjectDirectory}/docs/modules/ROOT/partials/ @@ -36,6 +43,12 @@ docs + + + src/main/antora/resources/antora-resources + true + + pl.project13.maven @@ -45,17 +58,44 @@ org.apache.maven.plugins maven-dependency-plugin - - org.apache.maven.plugins - maven-resources-plugin - org.codehaus.mojo exec-maven-plugin + + + + generate-observability-docs + ${generate-docs.phase} + + java + + + io.micrometer.docs.DocsGeneratorCommand + true + + ${micrometer-docs-generator.inputPath} + ${micrometer-docs-generator.inclusionPattern} + ${micrometer-docs-generator.outputPath} + + + + + + + io.micrometer + micrometer-docs-generator + ${micrometer-docs-generator.version} + jar + + + + + io.spring.maven.antora + antora-component-version-maven-plugin - org.asciidoctor - asciidoctor-maven-plugin + io.spring.maven.antora + antora-maven-plugin org.apache.maven.plugins diff --git a/docs/src/main/antora/resources/antora-resources/antora.yml b/docs/src/main/antora/resources/antora-resources/antora.yml new file mode 100644 index 00000000..9148923f --- /dev/null +++ b/docs/src/main/antora/resources/antora-resources/antora.yml @@ -0,0 +1,20 @@ +version: @antora-component.version@ +prerelease: @antora-component.prerelease@ + +asciidoc: + attributes: + attribute-missing: 'warn' + chomp: 'all' + project-root: @maven.multiModuleProjectDirectory@ + github-repo: @docs.main@ + github-raw: https://raw.githubusercontent.com/spring-cloud/@docs.main@/@github-tag@ + github-code: https://github.com/spring-cloud/@docs.main@/tree/@github-tag@ + github-issues: https://github.com/spring-cloud/@docs.main@/issues/ + github-wiki: https://github.com/spring-cloud/@docs.main@/wiki + spring-cloud-version: @project.version@ + github-tag: @github-tag@ + version-type: @version-type@ + docs-url: https://docs.spring.io/@docs.main@/docs/@project.version@ + raw-docs-url: https://raw.githubusercontent.com/spring-cloud/@docs.main@/@github-tag@ + project-version: @project.version@ + project-name: @docs.main@ diff --git a/docs/modules/ROOT/pages/README.adoc b/docs/src/main/asciidoc/README.adoc similarity index 100% rename from docs/modules/ROOT/pages/README.adoc rename to docs/src/main/asciidoc/README.adoc diff --git a/docs/modules/ROOT/pages/sagan-boot.adoc b/docs/src/main/asciidoc/sagan-boot.adoc similarity index 100% rename from docs/modules/ROOT/pages/sagan-boot.adoc rename to docs/src/main/asciidoc/sagan-boot.adoc diff --git a/docs/modules/ROOT/pages/sagan-index.adoc b/docs/src/main/asciidoc/sagan-index.adoc similarity index 100% rename from docs/modules/ROOT/pages/sagan-index.adoc rename to docs/src/main/asciidoc/sagan-index.adoc