Antora migration (#1446)

* Migrate Structure

* Insert explicit ids for headers

* Remove unnecessary asciidoc attributes

* Copy default antora files

* Fix indentation for all pages

* Split files

* Generate a default navigation

* Remove includes

* Fix cross references

* Enable Section Summary TOC for small pages

* Antora migration

.github/workflows/deploy-docs.yml

@@ -0,0 +1,32 @@
+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)

.gitignore

@@ -84,3 +84,9 @@ crashlytics-build.properties
 .vscode/
 .java-version
 *Dockerfile
+
+node
+node_modules
+build
+package.json
+package-lock.json

.mvn/maven.config

@@ -1 +1 @@
--DaltSnapshotDeploymentRepository=repo.spring.io::default::https://repo.spring.io/libs-snapshot-local -P spring
+-P spring

.mvn/wrapper/maven-wrapper.properties

@@ -1 +1,2 @@
-distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.5.4/apache-maven-3.5.4-bin.zip
+distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.0/apache-maven-3.9.0-bin.zip
+wrapperUrl=https://repo.maven.apache.org/maven2/io/takari/maven-wrapper/0.5.6/maven-wrapper-0.5.6.jar

docs/antora-playbook.yml

@@ -0,0 +1,38 @@
+antora:
+  extensions:
+    - '@springio/antora-extensions/partial-build-extension'
+    - require: '@springio/antora-extensions/latest-version-extension'
+    - require: '@springio/antora-extensions/inject-collector-cache-config-extension'
+    - '@antora/collector-extension'
+    - '@antora/atlas-extension'
+    - require: '@springio/antora-extensions/root-component-extension'
+      root_component_name: 'cloud-kubernetes'
+site:
+  title: Spring Cloud Kubernetes
+  url: https://docs.spring.io/spring-cloud-kubernetes/reference/
+content:
+  sources:
+    - url: ./..
+      branches: HEAD
+      start_path: docs
+      worktrees: true
+asciidoc:
+  attributes:
+    page-stackoverflow-url: https://stackoverflow.com/tags/spring-cloud
+    page-pagination: ''
+    hide-uri-scheme: '@'
+    tabs-sync-option: '@'
+    chomp: 'all'
+  extensions:
+    - '@asciidoctor/tabs'
+    - '@springio/asciidoctor-extensions'
+  sourcemap: true
+urls:
+  latest_version_segment: ''
+runtime:
+  log:
+    failure_level: warn
+    format: pretty
+ui:
+  bundle:
+    url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.3.5/ui-bundle.zip

docs/antora.yml

@@ -0,0 +1,12 @@
+name: cloud-kubernetes
+version: true
+title: Spring Cloud Kubernetes
+nav:
+  - modules/ROOT/nav.adoc
+ext:
+  collector:
+    run:
+      command: ./mvnw --no-transfer-progress -B process-resources -Pdocs -pl docs -Dantora-maven-plugin.phase=none -Dgenerate-docs.phase=none -Dgenerate-readme.phase=none -Dgenerate-cloud-resources.phase=none -Dmaven-dependency-plugin-for-docs.phase=none -Dmaven-dependency-plugin-for-docs-classes.phase=none -DskipTests
+      local: true
+    scan:
+      dir: ./target/classes/antora-resources/

docs/modules/ROOT/nav.adoc

@@ -0,0 +1,24 @@
+* xref:index.adoc[Introduction]
+* xref:getting-started.adoc[]
+* xref:discovery-client.adoc[]
+* xref:discovery-kubernetes-native.adoc[]
+* xref:property-source-config.adoc[]
+** xref:property-source-config/configmap-propertysource.adoc[]
+** xref:property-source-config/secrets-propertysource.adoc[]
+** xref:property-source-config/namespace-resolution.adoc[]
+** xref:property-source-config/order_of_configMaps_and_secrets.adoc[]
+** xref:property-source-config/propertysource-reload.adoc[]
+** xref:property-source-config/namespace-label-filtering.adoc[]
+* xref:kubernetes-awareness.adoc[]
+* xref:pod-health-indicator.adoc[]
+* xref:info-contributor.adoc[]
+* xref:leader-election.adoc[]
+* xref:load-balancer.adoc[]
+* xref:security-service-accounts.adoc[]
+* xref:service-registry.adoc[]
+* xref:spring-cloud-kubernetes-configuration-watcher.adoc[]
+* xref:spring-cloud-kubernetes-configserver.adoc[]
+* xref:spring-cloud-kubernetes-discoveryserver.adoc[]
+* xref:examples.adoc[]
+* xref:other-resources.adoc[]
+* xref:appendix.adoc[]

docs/src/main/asciidoc/_attributes.adoc → docs/modules/ROOT/pages/_attributes.adoc

@@ -1,8 +1,6 @@
 :doctype: book
 :idprefix:
 :idseparator: -
-:toc: left
-:toclevels: 4
 :tabsize: 4
 :numbered:
 :sectanchors:

docs/src/main/asciidoc/appendix.adoc → docs/modules/ROOT/pages/appendix.adoc

@@ -1,7 +1,8 @@
 :numbered!:
 [appendix]
 [[common-application-properties]]
-== Common application properties
+= Common application properties
+:page-section-summary-toc: 1
 
 include::_attributes.adoc[]
 
@@ -11,4 +12,4 @@ This appendix provides a list of common {project-full-name} properties and refer
 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::_configprops.adoc[]
+include::partial$_configprops.adoc[]

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[]

docs/src/main/asciidoc/discovery-client.adoc → docs/modules/ROOT/pages/discovery-client.adoc

@@ -1,4 +1,5 @@
-== DiscoveryClient for Kubernetes
+[[discoveryclient-for-kubernetes]]
+= DiscoveryClient for Kubernetes
 
 This project provides an implementation of https://github.com/spring-cloud/spring-cloud-commons/blob/master/spring-cloud-commons/src/main/java/org/springframework/cloud/client/discovery/DiscoveryClient.java[Discovery Client]
 for https://kubernetes.io[Kubernetes].
@@ -10,7 +11,6 @@ DiscoveryClient can also find services of type `ExternalName` (see https://kuber
 
 This is something that you get for free by adding the following dependency inside your project:
 
-====
 HTTP Based `DiscoveryClient`
 [source,xml]
 ----
@@ -19,12 +19,10 @@ HTTP Based `DiscoveryClient`
     <artifactId>spring-cloud-starter-kubernetes-discoveryclient</artifactId>
 </dependency>
 ----
-====
 
 NOTE: `spring-cloud-starter-kubernetes-discoveryclient` is designed to be used with the
-<<spring-cloud-kubernetes-discoveryserver, Spring Cloud Kubernetes DiscoveryServer>>.
+xref:spring-cloud-kubernetes-discoveryserver.adoc#spring-cloud-kubernetes-discoveryserver[Spring Cloud Kubernetes DiscoveryServer].
 
-====
 Fabric8 Kubernetes Client
 [source,xml]
 ----
@@ -33,9 +31,7 @@ Fabric8 Kubernetes Client
     <artifactId>spring-cloud-starter-kubernetes-fabric8</artifactId>
 </dependency>
 ----
-====
 
-====
 Kubernetes Java Client
 [source,xml]
 ----
@@ -44,11 +40,9 @@ Kubernetes Java Client
     <artifactId>spring-cloud-starter-kubernetes-client</artifactId>
 </dependency>
 ----
-====
 
 To enable loading of the `DiscoveryClient`, add `@EnableDiscoveryClient` to the according configuration or application class, as the following example shows:
 
-====
 [source,java]
 ----
 @SpringBootApplication
@@ -59,46 +53,37 @@ public class Application {
   }
 }
 ----
-====
 
 Then you can inject the client in your code simply by autowiring it, as the following example shows:
 
-====
 [source,java]
 ----
 @Autowired
 private DiscoveryClient discoveryClient;
 ----
-====
 
 You can choose to enable `DiscoveryClient` from all namespaces by setting the following property in `application.properties`:
 
-====
 [source]
 ----
 spring.cloud.kubernetes.discovery.all-namespaces=true
 ----
-====
 
 To discover services and endpoints only from specified namespaces you should set property `all-namespaces` to `false` and set the following property in `application.properties` (in this example namespaces are: `ns1` and `ns2`).
 
-====
 [source]
 ----
 spring.cloud.kubernetes.discovery.namespaces[0]=ns1
 spring.cloud.kubernetes.discovery.namespaces[1]=ns2
 ----
-====
 
 To discover service endpoint addresses that are not marked as "ready" by the kubernetes api server, you can set the following property in `application.properties` (default: false):
 
-====
 [source]
 ----
 spring.cloud.kubernetes.discovery.include-not-ready-addresses=true
 ----
 NOTE: This might be useful when discovering services for monitoring purposes, and would enable inspecting the `/health` endpoint of not-ready service instances.
-====
 
 If your service exposes multiple ports, you will need to specify which port the `DiscoveryClient` should use.
 The `DiscoveryClient` will choose the port using the following logic.
@@ -122,12 +107,10 @@ As said before, if you want to get the list of `ServiceInstance` to also include
 
 If, for any reason, you need to disable the `DiscoveryClient`, you can set the following property in `application.properties`:
 
-====
 [source]
 ----
 spring.cloud.kubernetes.discovery.enabled=false
 ----
-====
 
 Some Spring Cloud components use the `DiscoveryClient` in order to obtain information about the local service instance. For
 this to work, you need to align the Kubernetes service name with the `spring.application.name` property.
@@ -155,7 +138,7 @@ spring:
           - namespace-b
 ```
 
-- we will use: xref:property-source-config.adoc#namespace-resolution[Namespace Resolution] if the above two paths are not taken.
+- we will use: xref:property-source-config/namespace-resolution.adoc[Namespace Resolution] if the above two paths are not taken.
 
 In order to enable this functionality you need to add
 `@EnableScheduling` on a configuration class in your application.

docs/src/main/asciidoc/discovery-kubernetes-native.adoc → docs/modules/ROOT/pages/discovery-kubernetes-native.adoc

@@ -1,9 +1,11 @@
-== Kubernetes native service discovery
+[[kubernetes-native-service-discovery]]
+= Kubernetes native service discovery
+:page-section-summary-toc: 1
 
 Kubernetes itself is capable of (server side) service discovery (see: https://kubernetes.io/docs/concepts/services-networking/service/#discovering-services).
 Using native kubernetes service discovery ensures compatibility with additional tooling, such as Istio (https://istio.io), a service mesh that is capable of load balancing, circuit breaker, failover, and much more.
 
-The caller service then need only refer to names resolvable in a particular Kubernetes cluster. A simple implementation might use a spring `RestTemplate` that refers to a fully qualified domain name (FQDN), such as `https://{service-name}.{namespace}.svc.{cluster}.local:{service-port}`.
+The caller service then need only refer to names resolvable in a particular Kubernetes cluster. A simple implementation might use a spring `RestTemplate` that refers to a fully qualified domain name (FQDN), such as `https://\{service-name}.\{namespace}.svc.\{cluster}.local:\{service-port}`.
 
 Additionally, you can use Hystrix for:
 

docs/src/main/asciidoc/examples.adoc → docs/modules/ROOT/pages/examples.adoc

@@ -1,4 +1,6 @@
-== Examples
+[[examples]]
+= Examples
+:page-section-summary-toc: 1
 
 Spring Cloud Kubernetes tries to make it transparent for your applications to consume Kubernetes Native Services by
 following the Spring Cloud interfaces.

docs/src/main/asciidoc/getting-started.adoc → docs/modules/ROOT/pages/getting-started.adoc

@@ -1,4 +1,5 @@
-== Starters
+[[starters]]
+= Starters
 
 Starters are convenient dependency descriptors you can include in your
 application. Include a starter to get the dependencies and Spring Boot
@@ -49,8 +50,8 @@ resolves service names to Kubernetes Services.
 </dependency>
 ----
 | Load application properties from Kubernetes
-<<configmap-propertysource,ConfigMaps>> and <<Secrets PropertySource,Secrets>>.
-<<propertysource-reload,Reload>> application properties when a ConfigMap or
+xref:property-source-config/configmap-propertysource.adoc[ConfigMaps] and <<Secrets PropertySource,Secrets>>.
+xref:property-source-config/propertysource-reload.adoc[Reload] application properties when a ConfigMap or
 Secret changes.
 
 | [source,xml]

docs/modules/ROOT/pages/index.adoc

@@ -0,0 +1 @@
+include::spring-cloud-kubernetes.adoc[Introduction]

docs/src/main/asciidoc/info-contributor.adoc → docs/modules/ROOT/pages/info-contributor.adoc

@@ -1,4 +1,6 @@
-== Info Contributor
+[[info-contributor]]
+= Info Contributor
+:page-section-summary-toc: 1
 
 Spring Cloud Kubernetes includes an `InfoContributor` which adds Pod information to
 Spring Boot's `/info` Acturator endpoint.

docs/src/main/asciidoc/kubernetes-awareness.adoc → docs/modules/ROOT/pages/kubernetes-awareness.adoc

@@ -1,4 +1,5 @@
-== Kubernetes Ecosystem Awareness
+[[kubernetes-ecosystem-awareness]]
+= Kubernetes Ecosystem Awareness
 
 All features described earlier in this guide work equally well, regardless of whether your application is running inside
 Kubernetes. This is really helpful for development and troubleshooting.
@@ -20,19 +21,22 @@ you will have to set `spring.main.cloud-platform` should be set in `bootstrap.{p
 (or the profile specific one).  Also note that these properties: `spring.cloud.kubernetes.config.enabled` and `spring.cloud.kubernetes.secrets.enabled`
 will only take effect when set in `bootstrap.{properties|yml}` when you have `spring-cloud-starter-bootstrap` on your classpath or are setting `spring.cloud.bootstrap.enabled=true`.
 
-=== Breaking Changes In 3.0.x
+[[breaking-changes-in-3-0-x]]
+== Breaking Changes In 3.0.x
 
 In versions of Spring Cloud Kubernetes prior to `3.0.x`, Kubernetes awareness was implemented using `spring.cloud.kubernetes.enabled` property. This
 property was removed and is un-supported. Instead, we use Spring Boot API: https://docs.spring.io/spring-boot/docs/current/api/org/springframework/boot/autoconfigure/condition/ConditionalOnCloudPlatform.html[ConditionalOnCloudPlatform].
 If it is needed to explicitly enable or disable this awareness, use `spring.main.cloud-platform=NONE/KUBERNETES`.
 
-=== Kubernetes Profile Autoconfiguration
+[[kubernetes-profile-autoconfiguration]]
+== Kubernetes Profile Autoconfiguration
 
 When the application runs as a pod inside Kubernetes, a Spring profile named `kubernetes` automatically gets activated.
 This lets you customize the configuration, to define beans that are applied when the Spring Boot application is deployed
 within the Kubernetes platform (for example, different development and production configuration).
 
-=== Istio Awareness
+[[istio-awareness]]
+== Istio Awareness
 
 When you include the `spring-cloud-kubernetes-fabric8-istio` module in the application classpath, a new profile is added to the application,
 provided the application is running inside a Kubernetes Cluster with https://istio.io[Istio] installed. You can then use

docs/src/main/asciidoc/leader-election.adoc → docs/modules/ROOT/pages/leader-election.adoc

@@ -1,4 +1,6 @@
-== Leader Election
+[[leader-election]]
+= Leader Election
+
 The Spring Cloud Kubernetes leader election mechanism implements the leader election API of Spring Integration using a Kubernetes ConfigMap.
 
 Multiple application instances compete for leadership, but leadership will only be granted to one.
@@ -9,7 +11,6 @@ When leadership removal occurs, the previous leader receives `OnRevokedEvent` ap
 After removal, any instances in the cluster may become the new leader, including the old leader.
 
 To include it in your project, add the following dependency.
-====
 Fabric8 Leader Implementation
 [source,xml]
 ----
@@ -18,12 +19,9 @@ Fabric8 Leader Implementation
 	<artifactId>spring-cloud-kubernetes-fabric8-leader</artifactId>
 </dependency>
 ----
-====
 
 To specify the name of the configmap used for leader election use the following property.
-====
 [source,properties]
 ----
 spring.cloud.kubernetes.leader.config-map-name=leader
 ----
-====