Spring Cloud Task generates documentation for Antora infra

Migrate Structure

Insert explicit ids for headers

Remove unnecessary asciidoc attributes

Copy default antora files

Fix indentation for all pages

Generate a default navigation

Remove includes

Fix cross references

Enable Section Summary TOC for small pages

WIP

Nav.adoc now represents a list of navigation properties

Warning and errors are now resolved.
Observability docs now present in navigation bar and properly visible

Index.adoc contains preface information .

Nav.adoc contains proper ordering for appendix information

.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

@@ -34,3 +34,9 @@ spring-*/src/main/java/META-INF/MANIFEST.MF
 
 # Github Actions
 .m2
+
+node
+node_modules
+build
+package.json
+package-lock.json

README.adoc

@@ -5,24 +5,28 @@ Edit the files in the src/main/asciidoc/ directory instead.
 ////
 
 
+[[spring-cloud-task]]
 = Spring Cloud Task
 
 Is a project centered around the idea of processing on demand.  A user is able to develop
 a “task” that can be deployed, executed and removed on demand, yet the result of the
 process persists beyond the life of the task for future reporting.
 
 
+[[requirements:]]
 == Requirements:
 
 * Java 17 or Above
 
+[[build-main-project:]]
 == Build Main Project:
 
 [source,shell,indent=2]
 ----
 $ ./mvnw clean install
 ----
 
+[[example:]]
 == Example:
 
 [source,java,indent=2]
@@ -50,9 +54,11 @@ public class MyApp {
 }
 ----
 
+[[code-of-conduct]]
 == Code of Conduct
 This project adheres to the Contributor Covenant link:CODE_OF_CONDUCT.adoc[code of conduct]. By participating, you  are expected to uphold this code. Please report unacceptable behavior to [email protected].
 
+[[building-the-project]]
 == Building the Project
 
 This project requires that you invoke the Javadoc engine from the Maven command line. You can do so by appending `javadoc:aggregate` to the rest of your Maven command.

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-task'
+site:
+  title: Spring Cloud Task
+  url: https://docs.spring.io/spring-cloud-task/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-task
+version: true
+title: spring-cloud-task
+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,11 @@
+* xref:index.adoc[]
+* xref:preface.adoc[]
+* xref:getting-started.adoc[]
+* xref:features.adoc[]
+* xref:batch.adoc[]
+* xref:batch-starter.adoc[]
+* xref:stream.adoc[]
+* xref:appendix.adoc[]
+** xref:appendix-task-repository-schema.adoc[]
+** xref:appendix-building-the-documentation.adoc[]
+** xref:observability.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-building-the-documentation.adoc → docs/modules/ROOT/pages/appendix-building-the-documentation.adoc

@@ -1,6 +1,7 @@
 
 [[appendix-building-the-documentation]]
-== Building This Documentation
+= Building This Documentation
+:page-section-summary-toc: 1
 
 This project uses Maven to generate this documentation. To generate it for yourself,
 run the following command: `$ mvn clean install -DskipTests -P docs`.

docs/src/main/asciidoc/appendix-task-repository-schema.adoc → docs/modules/ROOT/pages/appendix-task-repository-schema.adoc

@@ -1,5 +1,5 @@
 [[appendix-task-repository-schema]]
-== Task Repository Schema
+= Task Repository Schema
 
 [[partintro]]
 --
@@ -8,7 +8,8 @@ This appendix provides an ERD for the database schema used in the task repositor
 
 image::task_schema.png[]
 
-=== Table Information
+[[table-information]]
+== Table Information
 --
 
 .TASK_EXECUTION
@@ -34,9 +35,9 @@ Spring Cloud Task Framework at app startup establishes the next available id as
 
 |LAST_UPDATED |TRUE | TIMESTAMP | X | Spring Cloud Task Framework at app startup establishes the value. Or if the record is created outside of task then the value must be populated at record creation time.
 
-|EXTERNAL_EXECUTION_ID |FALSE | VARCHAR | 250 | If the `spring.cloud.task.external-execution-id` property is set then Spring Cloud Task Framework at app startup will set this to the value specified.   More information can be found <<features-external_task_id,here>>
+|EXTERNAL_EXECUTION_ID |FALSE | VARCHAR | 250 | If the `spring.cloud.task.external-execution-id` property is set then Spring Cloud Task Framework at app startup will set this to the value specified.   More information can be found xref:features.adoc#features-external_task_id[here]
 
-|PARENT_TASK_EXECUTION_ID |FALSE |BIGINT | X | If the `spring.cloud.task.parent-execution-id` property is set then Spring Cloud Task Framework at app startup will set this to the value specified.   More information can be found <<features-parent_task_id,here>>
+|PARENT_TASK_EXECUTION_ID |FALSE |BIGINT | X | If the `spring.cloud.task.parent-execution-id` property is set then Spring Cloud Task Framework at app startup will set this to the value specified.   More information can be found xref:features.adoc#features-parent_task_id[here]
 
 |=========================================================
 
@@ -65,7 +66,7 @@ Used to link the task execution to the batch execution.
 
 
 .TASK_LOCK
-Used for the `single-instance-enabled` feature discussed <<features-single-instance-enabled,here>>.
+Used for the `single-instance-enabled` feature discussed xref:features.adoc#features-single-instance-enabled[here].
 [width="80%", cols="1,1,1,1,10", options="header"]
 |=========================================================
 |Column Name |Required |Type | Field Length |Notes
@@ -84,7 +85,8 @@ Used for the `single-instance-enabled` feature discussed <<features-single-insta
 NOTE: The DDL for setting up tables for each database type can be found https://github.com/spring-cloud/spring-cloud-task/tree/master/spring-cloud-task-core/src/main/resources/org/springframework/cloud/task[here].
 --
 
-=== SQL Server
+[[sql-server]]
+== SQL Server
 By default Spring Cloud Task uses a sequence table for determining the `TASK_EXECUTION_ID` for the `TASK_EXECUTION` table.
 However, when launching multiple tasks simultaneously while using SQL Server, this can cause a deadlock to occur on the `TASK_SEQ` table.
 The resolution is to drop the `TASK_EXECUTION_SEQ` table and create a sequence using the same name.   For example:

docs/modules/ROOT/pages/appendix.adoc

@@ -0,0 +1,10 @@
+
+[[appendix]]
+= Appendices
+:page-section-summary-toc: 1
+
+
+
+ifndef::train-docs[]
+endif::[]
+

docs/src/main/asciidoc/batch-starter.adoc → docs/modules/ROOT/pages/batch-starter.adoc

@@ -13,7 +13,6 @@ https://spring.io/projects/spring-batch[Spring Batch documentation].
 
 To obtain the starter for Maven, add the following to your build:
 
-====
 [source,xml]
 ----
 <dependency>
@@ -22,16 +21,13 @@ To obtain the starter for Maven, add the following to your build:
     <version>2.3.0</version>
 </dependency>
 ----
-====
 
 To obtain the starter for Gradle, add the following to your build:
 
-====
 [source,groovy]
 ----
 compile "org.springframework.cloud:spring-cloud-starter-single-step-batch-job:2.3.0"
 ----
-====
 
 [[job-definition]]
 == Defining a Job
@@ -625,6 +621,7 @@ Second, this starter lets you configure two properties on the writer.
 
 For more about the configuration options for the `KafkaItemWriter`, see the  https://docs.spring.io/spring-batch/docs/4.3.x/api/org/springframework/batch/item/kafka/KafkaItemWriter.html[`KafkaItemWiter` documentation].
 
+[[spring-aot]]
 === Spring AOT
 When using Spring AOT with Single Step Batch Starter you must set the reader and
 writer name properties at compile time (unless you create a bean(s) for the reader and or writer).

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

@@ -135,6 +135,7 @@ NOTE: You can find a sample remote partition application in the samples module o
 Spring Cloud Task project,
 https://github.com/spring-cloud/spring-cloud-task/tree/master/spring-cloud-task-samples/partitioned-batch-job[here].
 
+[[asynchronously-launch-remote-batch-partitions]]
 === Asynchronously launch remote batch partitions
 
 By default batch partitions are launched sequentially.   However, in some cases this may affect performance as each launch will block until the resource (For example: provisioning a pod in Kubernetes) is provisioned.
@@ -169,6 +170,7 @@ For example:
 NOTE: We need to close the context since the use of `ThreadPoolTaskExecutor` leaves a thread active thus the app will not terminate. To close the application appropriately, we will need to set `spring.cloud.task.closecontextEnabled` property to `true`.
 
 
+[[notes-on-developing-a-batch-partitioned-application-for-the-kubernetes-platform]]
 === Notes on Developing a Batch-partitioned application for the Kubernetes Platform
 
 * When deploying partitioned apps on the Kubernetes platform, you must use the following
@@ -190,12 +192,12 @@ Otherwise, an exception is thrown.
 == Batch Informational Messages
 
 Spring Cloud Task provides the ability for batch jobs to emit informational messages. The
-"`<<stream.adoc#stream-integration-batch-events>>`" section covers this feature in detail.
+"`xref:stream.adoc#stream-integration-batch-events[Spring Batch Events]`" section covers this feature in detail.
 
 [[batch-failures-and-tasks]]
 == Batch Job Exit Codes
 
-As discussed <<features.adoc#features-lifecycle-exit-codes,earlier>>, Spring Cloud Task
+As discussed xref:features.adoc#features-lifecycle-exit-codes[earlier], Spring Cloud Task
 applications support the ability to record the exit code of a task execution. However, in
 cases where you run a Spring Batch Job within a task, regardless of how the Batch Job
 Execution completes, the result of the task is always zero when using the default

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/features.adoc → docs/modules/ROOT/pages/features.adoc

@@ -98,7 +98,7 @@ boot application.
 === Mapping Exit Codes
 
 When a task completes, it tries to return an exit code to the OS. If we take a look
-at our <<getting-started-developing-first-task,original example>>, we can see that we are
+at our xref:getting-started.adoc#getting-started-developing-first-task[original example], we can see that we are
 not controlling that aspect of our application. So, if an exception is thrown, the JVM
 returns a code that may or may not be of any use to you in debugging.
 
@@ -372,6 +372,7 @@ application:
 NOTE: The exit code for the application will be 1 if the task fails because this feature
 is enabled and another task is running with the same task name.
 
+[[single-instance-usage-for-spring-aot-and-native-compilation]]
 ==== Single Instance Usage for Spring AOT And Native Compilation
 To use Spring Cloud Task's single-instance feature when creating a natively compiled app, you need to enable the feature at build time.
 To do so, add the process-aot execution and set `spring.cloud.task.single-step-instance-enabled=true` as a JVM argument, as follows:
@@ -394,13 +395,15 @@ To do so, add the process-aot execution and set `spring.cloud.task.single-step-i
     </executions>
 </plugin>
 
+[[enabling-observations-for-applicationrunner-and-commandlinerunner]]
 === Enabling  Observations for ApplicationRunner and CommandLineRunner
 
 
 To Enable Task Observations for `ApplicationRunner` or `CommandLineRunner` set `spring.cloud.task.observation.enabled` to true.
 
 An example task application with observations enables using the `SimpleMeterRegistry` can be found https://github.com/spring-cloud/spring-cloud-task/tree/main/spring-cloud-task-samples/task-observations[here].
 
+[[disabling-spring-cloud-task-auto-configuration]]
 === Disabling Spring Cloud Task Auto Configuration
 
 In cases where Spring Cloud Task should not be autoconfigured for an implementation, you can disable Task's auto configuration.

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

@@ -23,6 +23,7 @@ environment.
 You need to have Java installed (Java 17 or better). To build, you need to have Maven
 installed as well.
 
+[[database-requirements]]
 === Database Requirements
 
 Spring Cloud Task uses a relational database to store the results of an executed task.
@@ -136,7 +137,7 @@ In our demo, the `TaskRepository` uses an embedded H2 database to record the res
 of a task. This H2 embedded database is not a practical solution for a production environment, since
 the H2 DB goes away once the task ends. However, for a quick getting-started
 experience, we can use this in our example as well as echoing to the logs what is being updated
-in that repository. In the <<features-configuration>> section (later in this
+in that repository. In the xref:features.adoc#features-configuration[Configuration] section (later in this
 documentation), we cover how to customize the configuration of the pieces provided by
 Spring Cloud Task.
 

docs/modules/ROOT/pages/index.adoc

@@ -0,0 +1,25 @@
+[[spring-cloud-task-reference-guide]]
+= Spring Cloud Task Reference Guide
+:page-section-summary-toc: 1
+Michael Minella, Glenn Renfro, Jay Bryant
+
+
+// ======================================================================================
+
+Version {project-version}
+
+(C) 2009-2022 VMware, Inc. All rights reserved.
+
+Copies of this document may be made for your own use and for distribution to
+others, provided that you do not charge any fee for such copies and further
+provided that each copy contains this Copyright Notice, whether distributed in
+print or electronically.
+
+
+
+
+
+
+
+
+// ======================================================================================

docs/modules/ROOT/pages/observability.adoc

@@ -0,0 +1,8 @@
+[[observability]]
+= Observability
+
+== Observability metadata
+
+include::partial$_metrics.adoc[]
+
+include::partial$_spans.adoc[]