Migrates documentation to Antora (#241)

* Migrate Structure

* Insert explicit ids for headers

* Copy default antora files

* Fix indentation for all pages

* Generate a default navigation

* Remove includes

* Enable Section Summary TOC for small pages

* WIP

* Updated the docs

* Removed unnecessary file deployment step

* Left deploy goal only

* Fixed configprops location

* Fixed gitignores and path of configprops generation

* Upgraded ui bundle

* Removed node files

* Removed unnecessary docs zip uploading

.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

@@ -18,4 +18,12 @@ _site/
 .factorypath
 .vscode/
 .flattened-pom.xml
-.DS_Store
+.DS_Store
+node_modules
+node
+_configprops.adoc
+_spans.adoc
+_metrics.adoc
+_conventions.adoc
+package.json
+package-lock.json

README.adoc

@@ -10,7 +10,8 @@ image::https://github.com/spring-cloud/spring-cloud-build/workflows/Build/badge.
 Spring Cloud Build is a common utility project for Spring Cloud
 to use for plugin and dependency management.
 
-== Building and Deploying
+[[building-and-deploying]]
+= Building and Deploying
 
 To install locally:
 
@@ -45,7 +46,8 @@ $ mvn deploy -P central -DaltReleaseDeploymentRepository=sonatype-nexus-staging:
 
 (the "central" profile is available for all projects in Spring Cloud and it sets up the gpg jar signing, and the repository has to be specified separately for this project because it is a parent of the starter parent which users in turn have as their own parent).
 
-== Contributing
+[[contributing]]
+= Contributing
 
 :spring-cloud-build-branch: master
 
@@ -278,7 +280,8 @@ If you need to add `ignoredClassPatterns` or `ignoredResourcePatterns` to your s
 ----
 
 
-== Flattening the POMs
+[[flattening-the-poms]]
+= Flattening the POMs
 
 To avoid propagating build setup that is required to build a Spring Cloud project, we're using the maven flatten plugin. It has the advantage of letting you use whatever features you need while publishing "clean" pom to the repository.
 
@@ -296,7 +299,8 @@ In order to add it, add the `org.codehaus.mojo:flatten-maven-plugin` to your `po
 </build>
 ----
 
-== Reusing the documentation
+[[reusing-the-documentation]]
+= Reusing the documentation
 
 Spring Cloud Build publishes its `spring-cloud-build-docs` module that contains
 helpful scripts (e.g. README generation ruby script) and css, xslt and images
@@ -305,9 +309,6 @@ approach of generating documentation just add these plugins to your `docs` modul
 
 [source,xml]
 ----
-<properties>
-    <upload-docs-zip.phase>deploy</upload-docs-zip.phase> <8>
-</properties>
 <profiles>
     <profile>
         <id>docs</id>
@@ -351,8 +352,6 @@ approach of generating documentation just add these plugins to your `docs` modul
 <4> This plugin generates an `adoc` file with all the configuration properties from the classpath
 <5> This plugin is required to parse the Asciidoctor documentation
 <6> This plugin is required to copy resources into proper final destinations and to generate main README.adoc and to assert that no files use unresolved links
-<7> This plugin ensures that the generated zip docs will get published
-<8> This property turns on the "deploy" phase for <7>
 
 IMPORTANT: The order of plugin declaration is important!
 
@@ -362,51 +361,13 @@ If you want to modify which of the configuration properties are put in the table
 
 Spring Cloud Build Docs comes with a set of attributes for asciidoctor that you can reuse.
 
-[source,xml]
+[source,yml]
 ----
-<attributes>
-    <docinfo>shared</docinfo>
-    <allow-uri-read>true</allow-uri-read>
-    <nofooter/>
-    <toc>left</toc>
-    <toc-levels>4</toc-levels>
-    <sectlinks>true</sectlinks>
-    <sources-root>${project.basedir}/src@</sources-root>
-    <asciidoc-sources-root>${project.basedir}/src/main/asciidoc@</asciidoc-sources-root>
-    <generated-resources-root>${project.basedir}/target/generated-resources@
-    </generated-resources-root>
-    <!-- Use this attribute the reference code from another module -->
-    <!-- Note the @ at the end, lowering the precedence of the attribute -->
-    <project-root>${maven.multiModuleProjectDirectory}@</project-root>
-    <!-- It's mandatory for you to pass the docs.main property -->
-    <github-repo>${docs.main}@</github-repo>
-    <github-project>https://github.com/spring-cloud/${docs.main}@</github-project>
-    <github-raw>
-        https://raw.githubusercontent.com/spring-cloud/${docs.main}/${github-tag}@
-    </github-raw>
-    <github-code>https://github.com/spring-cloud/${docs.main}/tree/${github-tag}@
-    </github-code>
-    <github-issues>https://github.com/spring-cloud/${docs.main}/issues/@</github-issues>
-    <github-wiki>https://github.com/spring-cloud/${docs.main}/wiki@</github-wiki>
-    <github-master-code>https://github.com/spring-cloud/${docs.main}/tree/master@
-    </github-master-code>
-    <index-link>${index-link}@</index-link>
-
-    <!-- Spring Cloud specific -->
-    <!-- for backward compatibility -->
-    <spring-cloud-version>${project.version}@</spring-cloud-version>
-    <project-version>${project.version}@</project-version>
-    <github-tag>${github-tag}@</github-tag>
-    <version-type>${version-type}@</version-type>
-    <docs-url>https://docs.spring.io/${docs.main}/docs/${project.version}@</docs-url>
-    <raw-docs-url>${github-raw}@</raw-docs-url>
-    <project-version>${project.version}@</project-version>
-    <project-name>${docs.main}@</project-name>
-    <source-highlighter>highlight.js</source-highlighter>
-</attributes>
+Unresolved directive in <stdin> - include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/docs/src/main/antora/resources/antora-resources/antora.yml[indent=0]
 ----
 
-== Updating the guides
+[[updating-the-guides]]
+= Updating the guides
 
 We assume that your project contains guides under the `guides` folder.
 

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-build'
+site:
+  title: Spring Cloud Build
+  url: https://docs.spring.io/spring-cloud-build/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-build
+version: true
+title: Spring Cloud Build
+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/modules/ROOT/nav.adoc

@@ -0,0 +1,3 @@
+* xref:index.adoc[]
+* xref:building.adoc[]
+* xref:contributing.adoc[]

docs/modules/ROOT/pages/building.adoc

@@ -0,0 +1,4 @@
+[[building]]
+= Building
+
+include::partial$building.adoc[]

docs/modules/ROOT/pages/contributing.adoc

@@ -0,0 +1,4 @@
+[[contributing]]
+= Contributing
+
+include::partial$contributing.adoc[]

docs/modules/ROOT/pages/index.adoc

@@ -0,0 +1,4 @@
+[[overview]]
+= Overview
+
+Spring Cloud Build is a common utility project for Spring Cloud to use for plugin and dependency management.

docs/src/main/asciidoc/building.adoc → docs/modules/ROOT/partials/building.adoc

@@ -1,6 +1,7 @@
 :jdkversion: 17
 
-=== Basic Compile and Test
+[[basic-compile-and-test]]
+== Basic Compile and Test
 
 To build the source you will need to install JDK {jdkversion}.
 
@@ -27,31 +28,36 @@ source control.
 The projects that require middleware (i.e. Redis) for testing generally
 require that a local instance of [Docker](https://www.docker.com/get-started) is installed and running.
 
-
-=== Documentation
+[[documentation]]
+== Documentation
 
 The spring-cloud-build module has a "docs" profile, and if you switch
-that on it will try to build asciidoc sources from
-`src/main/asciidoc`. As part of that process it will look for a
-`README.adoc` and process it by loading all the includes, but not
+that on it will try to build asciidoc sources using https://docs.antora.org/antora/latest/[Antora] from
+`modules/ROOT/`.
+
+As part of that process it will look for a
+`docs/src/main/asciidoc/README.adoc` and process it by loading all the includes, but not
 parsing or rendering it, just copying it to `${main.basedir}`
-(defaults to `${basedir}`, i.e. the root of the project). If there are
+(defaults to `$\{basedir}`, i.e. the root of the project). If there are
 any changes in the README it will then show up after a Maven build as
 a modified file in the correct place. Just commit it and push the change.
 
-=== Working with the code
+[[working-with-the-code]]
+== Working with the code
 If you don't have an IDE preference we would recommend that you use
 https://www.springsource.com/developer/sts[Spring Tools Suite] or
 https://eclipse.org[Eclipse] when working with the code. We use the
 https://eclipse.org/m2e/[m2eclipse] eclipse plugin for maven support. Other IDEs and tools
 should also work without issue as long as they use Maven 3.3.3 or better.
 
-==== Activate the Spring Maven profile
+[[activate-the-spring-maven-profile]]
+=== Activate the Spring Maven profile
 Spring Cloud projects require the 'spring' Maven profile to be activated to resolve
 the spring milestone and snapshot repositories. Use your preferred IDE to set this
 profile to be active, or you may experience build errors.
 
-==== Importing into eclipse with m2eclipse
+[[importing-into-eclipse-with-m2eclipse]]
+=== Importing into eclipse with m2eclipse
 We recommend the https://eclipse.org/m2e/[m2eclipse] eclipse plugin when working with
 eclipse. If you don't already have m2eclipse installed it is available from the "eclipse
 marketplace".
@@ -65,7 +71,8 @@ add the "spring" profile to your `settings.xml`. Alternatively you can
 copy the repository settings from the "spring" profile of the parent
 pom into your `settings.xml`.
 
-==== Importing into eclipse without m2eclipse
+[[importing-into-eclipse-without-m2eclipse]]
+=== Importing into eclipse without m2eclipse
 If you prefer not to use m2eclipse you can generate eclipse project metadata using the
 following command:
 

docs/src/main/asciidoc/code-of-conduct.adoc → docs/modules/ROOT/partials/code-of-conduct.adoc

@@ -1,5 +1,5 @@
-
-= Contributor Code of Conduct
+[[contributor-code-of-conduct]]
+== Contributor Code of Conduct
 
 As contributors and maintainers of this project, and in the interest of fostering an open
 and welcoming community, we pledge to respect all people who contribute through reporting
@@ -42,4 +42,4 @@ with regard to the reporter of an incident.
 
 This Code of Conduct is adapted from the
 https://contributor-covenant.org[Contributor Covenant], version 1.3.0, available at
-https://contributor-covenant.org/version/1/3/0/[contributor-covenant.org/version/1/3/0/]
+https://contributor-covenant.org/version/1/3/0/[contributor-covenant.org/version/1/3/0/]

docs/src/main/asciidoc/contributing-docs.adoc → docs/modules/ROOT/partials/contributing-docs.adoc

@@ -1 +1 @@
-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, please find the source code and issue trackers in the project at {github-project}[github].
+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, please find the source code and issue trackers in the project at {github-project}[github].