Antora (#1263)

* 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

* It's alive

* Fixed readme

Author: marcingrzejszczak

.github/workflows/deploy-docs.yml

@@ -0,0 +1,33 @@
+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
+    # FIXME: enable when pushed to spring-projects
+    # if: github.repository_owner == 'spring-projects'
+    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

@@ -21,3 +21,12 @@ _site/
 antrun
 .vscode/
 .flattened-pom.xml
+node
+node_modules
+build
+_configprops.adoc
+_spans.adoc
+_metrics.adoc
+_conventions.adoc
+package.json
+package-lock.json

README.adoc

@@ -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-commons'
+site:
+  title: Spring Cloud Commons
+  url: https://docs.spring.io/spring-cloud-commons/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.4/ui-bundle.zip

docs/antora-playbook.yml

@@ -0,0 +1,12 @@
+name: cloud-commons
+version: true
+title: Spring Cloud Commons
+nav:
+  - modules/ROOT/nav.adoc
+ext:
+  collector:
+    run:
+      command: ./mvnw validate process-resources -Pdocs -pl docs
+      local: true
+    scan:
+      dir: ./target/classes/antora-resources/

docs/antora.yml

@@ -0,0 +1,11 @@
+* xref:index.adoc[]
+** xref:intro.adoc[]
+** xref:spring-cloud-commons/application-context-services.adoc[]
+** xref:spring-cloud-commons/common-abstractions.adoc[]
+** xref:spring-cloud-commons/loadbalancer.adoc[]
+** xref:spring-cloud-commons/cachedrandompropertysource.adoc[]
+** xref:spring-cloud-commons/security.adoc[]
+* xref:spring-cloud-circuitbreaker.adoc[]
+* xref:appendix.adoc[]
+** xref:configprops.adoc[]
+

docs/modules/ROOT/nav.adoc

@@ -1,16 +1,18 @@
-:numbered!:
 [appendix]
 [[common-application-properties]]
-== Common application properties
+= Common application properties
 
-include::_attributes.adoc[]
+include::partial$_attributes.adoc[]
 
 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.
 
 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[]
+[[observability]]
+== Observability metadata
 
-include::_observability.adoc[]
+include::partial$_metrics.adoc[]
+
+include::partial$_spans.adoc[]

docs/src/main/asciidoc/appendix.adoc docs/modules/ROOT/pages/appendix.adocdocs/src/main/asciidoc/appendix.adoc renamed to docs/modules/ROOT/pages/appendix.adoc

@@ -0,0 +1,6 @@
+[[configuration-properties]]
+= Configuration Properties
+
+Below you can find a list of configuration properties.
+
+include::partial$_configprops.adoc[]

docs/modules/ROOT/pages/configprops.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].

docs/modules/ROOT/pages/index.adoc

@@ -1,3 +1,5 @@
+[[introduction]]
+= Introduction
 
 https://pivotal.io/platform-as-a-service/migrating-to-cloud-native-application-architectures-ebook[Cloud Native] is a style of application development that encourages easy adoption of best practices in the areas of continuous delivery and value-driven development.
 A related discipline is that of building https://12factor.net/[12-factor Applications], in which development practices are aligned with delivery and operations goals -- for instance, by using declarative programming and management and monitoring.
@@ -7,4 +9,3 @@ Spring Cloud facilitates these styles of development in a number of specific way
 Many of those features are covered by https://projects.spring.io/spring-boot[Spring Boot], on which Spring Cloud builds. Some more features are delivered by Spring Cloud as two libraries: Spring Cloud Context and Spring Cloud Commons.
 Spring Cloud Context provides utilities and special services for the `ApplicationContext` of a Spring Cloud application (bootstrap context, encryption, refresh scope, and environment endpoints). Spring Cloud Commons is a set of abstractions and common classes used in different Spring Cloud implementations (such as Spring Cloud Netflix and Spring Cloud Consul).
 
-include::jce.adoc[]