Antora migration

This commit is contained in:
spencergibb
2023-09-13 17:16:43 -04:00
parent a50ffe9e8e
commit bc6fab5966
30 changed files with 126 additions and 684 deletions

View File

@@ -1,32 +0,0 @@
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
# if: github.repository_owner == 'spring-cloud'
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)

View File

@@ -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-consul'
site:
title: PROJECT_FULL_NAME
url: https://docs.spring.io/PROJECT_NAME/reference/
title: Spring Cloud Consul
url: https://docs.spring.io/spring-cloud-consul/reference/
content:
sources:
- url: ./..

View File

@@ -1,6 +1,6 @@
name: PROJECT_WITHOUT_SPRING
name: cloud-consul
version: true
title: PROJECT_NAME
title: spring-cloud-consul
nav:
- modules/ROOT/nav.adoc
ext:

View File

@@ -1,20 +1,8 @@
* xref:index.adoc[]
* xref:spring-cloud-consul.adoc[]
** xref:spring-cloud-consul/quick-start.adoc[]
** xref:spring-cloud-consul/install.adoc[]
** xref:spring-cloud-consul/agent.adoc[]
** xref:spring-cloud-consul/discovery.adoc[]
** xref:spring-cloud-consul/config.adoc[]
** xref:spring-cloud-consul/retry.adoc[]
** xref:spring-cloud-consul/bus.adoc[]
** xref:spring-cloud-consul/hystrix.adoc[]
** xref:spring-cloud-consul/turbine.adoc[]
** xref:spring-cloud-consul/configuration-properties.adoc[]
* xref:_attributes.adoc[]
* xref:intro.adoc[]
* xref:quickstart.adoc[]
* xref:README.adoc[]
* xref:_configprops.adoc[]
* xref:install.adoc[]
* xref:discovery.adoc[]
* xref:config.adoc[]
* xref:retry.adoc[]
* xref:bus.adoc[]
* xref:appendix.adoc[]
* xref:sagan-boot.adoc[]
* xref:sagan-index.adoc[]

View File

@@ -6,8 +6,9 @@
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 Consul 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.
include::partial$_configprops.adoc[]

View File

@@ -1,6 +1,5 @@
[[spring-cloud-consul-bus]]
= Spring Cloud Bus with Consul
:page-section-summary-toc: 1
[[how-to-activate]]
== How to activate

View File

@@ -12,7 +12,7 @@ config/application/
The most specific property source is at the top, with the least specific at the bottom. Properties in the `config/application` folder are applicable to all applications using consul for configuration. Properties in the `config/testApp` folder are only available to the instances of the service named "testApp".
Configuration is currently read on startup of the application. Sending a HTTP POST to `/refresh` will cause the configuration to be reloaded. xref:spring-cloud-consul/config.adoc#spring-cloud-consul-config-watch[Config Watch] will also automatically detect changes and reload the application context.
Configuration is currently read on startup of the application. Sending a HTTP POST to `/refresh` will cause the configuration to be reloaded. xref:config.adoc#spring-cloud-consul-config-watch[Config Watch] will also automatically detect changes and reload the application context.
[[how-to-activate]]
== How to activate

View File

@@ -44,7 +44,7 @@ spring:
port: 8500
----
CAUTION: If you use xref:spring-cloud-consul/config.adoc[Spring Cloud Consul Config], and you have set `spring.cloud.bootstrap.enabled=true` or `spring.config.use-legacy-processing=true` or use `spring-cloud-starter-bootstrap`, then the above values will need to be placed in `bootstrap.yml` instead of `application.yml`.
CAUTION: If you use xref:config.adoc[Spring Cloud Consul Config], and you have set `spring.cloud.bootstrap.enabled=true` or `spring.config.use-legacy-processing=true` or use `spring-cloud-starter-bootstrap`, then the above values will need to be placed in `bootstrap.yml` instead of `application.yml`.
The default service name, instance id and port, taken from the `Environment`, are `${spring.application.name}`, the Spring Context ID and `${server.port}` respectively.
@@ -153,7 +153,7 @@ You can disable the HTTP health check entirely by setting `spring.cloud.consul.d
[[applying-headers]]
==== Applying Headers
Headers can be applied to health check requests. For example, if you're trying to register a https://cloud.spring.io/spring-cloud-config/[Spring Cloud Config] server that uses https://github.com/spring-cloud/spring-cloud-config/blob/master/docs/src/main/asciidoc/spring-cloud-config.adoc#vault-backend[Vault Backend]:
Headers can be applied to health check requests. For example, if you're trying to register a https://cloud.spring.io/spring-cloud-config/[Spring Cloud Config] server that uses https://github.com/spring-cloud/spring-cloud-config/blob/main/docs/src/main/asciidoc/spring-cloud-config.adoc#vault-backend[Vault Backend]:
.application.yml
----
@@ -338,7 +338,7 @@ With this metadata, and multiple service instances deployed on localhost, the ra
[[using-load-balancer]]
=== Using Load-balancer
Spring Cloud has support for https://github.com/spring-cloud/spring-cloud-netflix/blob/master/docs/src/main/asciidoc/spring-cloud-netflix.adoc#spring-cloud-feign[Feign] (a REST client builder) and also https://docs.spring.io/spring-cloud-commons/docs/current/reference/html/#rest-template-loadbalancer-client[Spring `RestTemplate`]
Spring Cloud has support for https://docs.spring.io/spring-cloud-openfeign/docs/current/reference/html/[Feign] (a REST client builder) and also https://docs.spring.io/spring-cloud-commons/docs/current/reference/html/#rest-template-loadbalancer-client[Spring `RestTemplate`]
for looking up services using the logical service names/ids instead of physical URLs. Both Feign and the discovery-aware RestTemplate utilize https://docs.spring.io/spring-cloud-commons/docs/current/reference/html/#spring-cloud-loadbalancer[Spring Cloud LoadBalancer] for client-side load balancing.
If you want to access service STORES using the RestTemplate simply declare:

View File

@@ -0,0 +1 @@
include::intro.adoc[]

View File

@@ -1,12 +1,14 @@
[[spring-cloud-consul-install]]
= Install Consul
// TODO: document using Testcontainers and SpringApplication.from()
Please see the https://www.consul.io/intro/getting-started/install.html[installation documentation] for instructions on how to install Consul.
[[spring-cloud-consul-agent]]
= Consul Agent
:page-section-summary-toc: 1
== Consul Agent
A Consul Agent client must be available to all Spring Cloud Consul applications. By default, the Agent client is expected to be at `localhost:8500`. See the https://consul.io/docs/agent/basics.html[Agent documentation] for specifics on how to start an Agent client and how to connect to a cluster of Consul Agent Servers. For development, after you have installed consul, you may start a Consul Agent using the following command:
----
./src/main/bash/local_run_consul.sh
----
A Consul Agent client must be available to all Spring Cloud Consul applications. By default, the Agent client is expected to be at `localhost:8500`. See the https://consul.io/docs/agent/basics.html[Agent documentation] for specifics on how to start an Agent client and how to connect to a cluster of Consul Agent Servers. Start a development agent according to the documentation above.
This will start an agent in server mode on port 8500, with the ui available at http://localhost:8500

View File

@@ -1,3 +1,6 @@
[[spring-cloud-gateway-intro]]
= Introduction
This project provides Consul integrations for Spring Boot apps through autoconfiguration
and binding to the Spring Environment and other Spring programming model idioms. With a few
simple annotations you can quickly enable and configure the common patterns inside your

View File

@@ -1,9 +1,12 @@
[[quickstart]]
= Quick Start
This quick start walks through using Spring Cloud Consul for Service Discovery and Distributed Configuration.
First, run Consul Agent on your machine. Then you can access it and use it as a Service Registry and Configuration source with Spring Cloud Consul.
[[discovery-client-usage]]
= Discovery Client Usage
== Discovery Client Usage
To use these features in an application, you can build it as a Spring Boot application that depends on `spring-cloud-consul-core`.
The most convenient way to add the dependency is with a Spring Boot starter: `org.springframework.cloud:spring-cloud-starter-consul-discovery`.
@@ -127,7 +130,7 @@ public String serviceUrl() {
----
[[distributed-configuration-usage]]
= Distributed Configuration Usage
== Distributed Configuration Usage
To use these features in an application, you can build it as a Spring Boot application that depends on `spring-cloud-consul-core` and `spring-cloud-consul-config`.
The most convenient way to add the dependency is with a Spring Boot starter: `org.springframework.cloud:spring-cloud-starter-consul-config`.
@@ -226,4 +229,4 @@ public class Application {
The application retrieves configuration data from Consul.
WARNING: If you use Spring Cloud Consul Config, you need to set the `spring.config.import` property in order to bind to Consul.
You can read more about it in the xref:spring-cloud-consul/config.adoc#config-data-import[Spring Boot Config Data Import section].
You can read more about it in the xref:config.adoc#config-data-import[Spring Boot Config Data Import section].

View File

@@ -1,6 +1,5 @@
[[spring-cloud-consul-retry]]
= Consul Retry
:page-section-summary-toc: 1
If you expect that the consul agent may occasionally be unavailable when
your app starts, you can ask it to keep trying after a failure. You need to add

View File

@@ -1,7 +0,0 @@
[[spring-cloud-consul]]
= Spring Cloud Consul
:page-section-summary-toc: 1
*{spring-cloud-version}*

View File

@@ -1,5 +0,0 @@
[[configuration-properties]]
= Configuration Properties
:page-section-summary-toc: 1
To see the list of all Consul related configuration properties please check link:appendix.html[the Appendix page].

View File

@@ -1,7 +0,0 @@
[[spring-cloud-consul-hystrix]]
= Circuit Breaker with Hystrix
:page-section-summary-toc: 1
Applications can use the Hystrix Circuit Breaker provided by the Spring Cloud Netflix project by including this starter in the projects pom.xml: `spring-cloud-starter-hystrix`. Hystrix doesn't depend on the Netflix Discovery Client. The `@EnableHystrix` annotation should be placed on a configuration class (usually the main class). Then methods can be annotated with `@HystrixCommand` to be protected by a circuit breaker. See https://projects.spring.io/spring-cloud/spring-cloud.html#_circuit_breaker_hystrix_clients[the documentation] for more details.

View File

@@ -1,6 +0,0 @@
[[spring-cloud-consul-install]]
= Install Consul
:page-section-summary-toc: 1
Please see the https://www.consul.io/intro/getting-started/install.html[installation documentation] for instructions on how to install Consul.

View File

@@ -1,6 +0,0 @@
[[quick-start]]
= Quick Start
:page-section-summary-toc: 1
include:../:quickstart.adoc[]

View File

@@ -1,42 +0,0 @@
[[spring-cloud-consul-turbine]]
= Hystrix metrics aggregation with Turbine and Consul
Turbine (provided by the Spring Cloud Netflix project), aggregates multiple instances Hystrix metrics streams, so the dashboard can display an aggregate view. Turbine uses the `DiscoveryClient` interface to lookup relevant instances. To use Turbine with Spring Cloud Consul, configure the Turbine application in a manner similar to the following examples:
.pom.xml
----
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-netflix-turbine</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-consul-discovery</artifactId>
</dependency>
----
Notice that the Turbine dependency is not a starter. The turbine starter includes support for Netflix Eureka.
.application.yml
----
spring.application.name: turbine
applications: consulhystrixclient
turbine:
aggregator:
clusterConfig: ${applications}
appConfig: ${applications}
----
The `clusterConfig` and `appConfig` sections must match, so it's useful to put the comma-separated list of service ID's into a separate configuration property.
.Turbine.java
----
@EnableTurbine
@SpringBootApplication
public class Turbine {
public static void main(String[] args) {
SpringApplication.run(DemoturbinecommonsApplication.class, args);
}
}
----

View File

@@ -81,4 +81,4 @@
|spring.cloud.consul.tls.key-store-password | | Password to an external keystore.
|spring.cloud.consul.tls.key-store-path | | Path to an external keystore.
|===
|===

View File

@@ -0,0 +1,6 @@
[[observability-conventions]]
=== Observability - Conventions
Below you can find a list of all `GlobalObservationConvention` and `ObservationConvention` declared by this project.

View File

@@ -0,0 +1,6 @@
[[observability-metrics]]
=== Observability - Metrics
Below you can find a list of all metrics declared by this project.

View File

@@ -0,0 +1,6 @@
[[observability-spans]]
=== Observability - Spans
Below you can find a list of all spans declared by this project.

View File

@@ -7,18 +7,24 @@
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-consul</artifactId>
<version>4.1.0-SNAPSHOT</version>
<relativePath>..</relativePath>
</parent>
<artifactId>spring-cloud-consul-docs</artifactId>
<packaging>jar</packaging>
<name>Spring Cloud Consul Docs</name>
<description>Spring Cloud Docs</description>
<description>Spring Cloud Consul Docs</description>
<properties>
<docs.main>spring-cloud-consul</docs.main>
<main.basedir>${basedir}/..</main.basedir>
<configprops.inclusionPattern>spring.cloud.consul.*</configprops.inclusionPattern>
<upload-docs-zip.phase>deploy</upload-docs-zip.phase>
<!-- Don't upload docs jar to central / repo.spring.io -->
<maven-deploy-plugin-default.phase>none</maven-deploy-plugin-default.phase>
<!-- Observability -->
<micrometer-docs-generator.version>1.0.2</micrometer-docs-generator.version>
<micrometer-docs-generator.inputPath>${maven.multiModuleProjectDirectory}/</micrometer-docs-generator.inputPath>
<micrometer-docs-generator.inclusionPattern>.*</micrometer-docs-generator.inclusionPattern>
<micrometer-docs-generator.outputPath>${maven.multiModuleProjectDirectory}/docs/modules/ROOT/partials/</micrometer-docs-generator.outputPath>
</properties>
<dependencies>
<dependency>
@@ -37,26 +43,32 @@
<profile>
<id>docs</id>
<build>
<resources>
<resource>
<directory>src/main/antora/resources/antora-resources</directory>
<filtering>true</filtering>
</resource>
</resources>
<plugins>
<plugin>
<groupId>pl.project13.maven</groupId>
<artifactId>git-commit-id-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-resources-plugin</artifactId>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<groupId>io.spring.maven.antora</groupId>
<artifactId>antora-component-version-maven-plugin</artifactId>
</plugin>
<plugin>
<groupId>io.spring.maven.antora</groupId>
<artifactId>antora-maven-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>

View File

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

View File

@@ -1,5 +1,5 @@
image::https://circleci.com/gh/spring-cloud/spring-cloud-consul/tree/master.svg?style=svg["CircleCI", link="https://circleci.com/gh/spring-cloud/spring-cloud-consul/tree/master"]
image::https://codecov.io/gh/spring-cloud/spring-cloud-consul/branch/master/graph/badge.svg["Codecov", link="https://codecov.io/gh/spring-cloud/spring-cloud-consul/branch/master"]
image::https://github.com/spring-cloud/spring-cloud-consul/workflows/Build/badge.svg?style=svg["Actions Status", link="https://github.com/spring-cloud/spring-cloud-consul/actions"]
image::https://codecov.io/gh/spring-cloud/spring-cloud-consul/branch/main/graph/badge.svg["Codecov", link="https://codecov.io/gh/spring-cloud/spring-cloud-consul/branch/main"]
[[quick-start]]
@@ -43,9 +43,9 @@ See the https://consul.io/intro/index.html[intro] for more information.
[[building]]
= Building
include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/building-jdk8.adoc[]
include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/docs/modules/ROOT/pages/building.adoc[]
[[contributing]]
= Contributing
include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/contributing.adoc[]
include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/docs/modules/ROOT/pages/contributing.adoc[]