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
2023-09-08 16:32:25 +02:00
parent dbbae91056
commit 9b4d7f09c1
31 changed files with 396 additions and 72 deletions
--- a/.github/workflows/deploy-docs.yml
+++ b/.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)
--- a/.gitignore
+++ b/.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
--- a/README.adoc
+++ b/README.adoc
@@ -5,6 +5,7 @@ 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
@@ -12,10 +13,12 @@ a “task” that can be deployed, executed and removed on demand, yet the resul
 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]
@@ -23,6 +26,7 @@ process persists beyond the life of the task for future reporting.
 $ ./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 spring-code-of-conduct@pivotal.io.

+[[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.
--- a/docs/antora-playbook.yml
+++ b/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
--- a/docs/antora.yml
+++ b/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/
--- a/docs/modules/ROOT/assets/images/task_schema.png
+++ b/docs/modules/ROOT/assets/images/task_schema.png
--- a/docs/modules/ROOT/nav.adoc
+++ b/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[]
--- a/docs/modules/ROOT/pages/_attributes.adoc
+++ b/docs/modules/ROOT/pages/_attributes.adoc
@@ -1,8 +1,6 @@
 :doctype: book
 :idprefix:
 :idseparator: -
-:toc: left
-:toclevels: 4
 :tabsize: 4
 :numbered:
 :sectanchors:
--- a/docs/modules/ROOT/pages/appendix-building-the-documentation.adoc
+++ b/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`.
--- a/docs/modules/ROOT/pages/appendix-task-repository-schema.adoc
+++ b/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:
--- a/docs/modules/ROOT/pages/appendix.adoc
+++ b/docs/modules/ROOT/pages/appendix.adoc
@@ -0,0 +1,10 @@
+
+[[appendix]]
+= Appendices
+:page-section-summary-toc: 1
+
+
+
+ifndef::train-docs[]
+endif::[]
+
--- a/docs/modules/ROOT/pages/batch-starter.adoc
+++ b/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).
--- a/docs/modules/ROOT/pages/batch.adoc
+++ b/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
--- a/docs/modules/ROOT/pages/configprops.adoc
+++ b/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[]
--- a/docs/modules/ROOT/pages/features.adoc
+++ b/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,6 +395,7 @@ 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


@@ -401,6 +403,7 @@ To Enable Task Observations for `ApplicationRunner` or `CommandLineRunner` set `

 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.
--- a/docs/modules/ROOT/pages/getting-started.adoc
+++ b/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.

--- a/docs/modules/ROOT/pages/index.adoc
+++ b/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.
+
+
+
+
+
+
+
+
+// ======================================================================================
--- a/docs/modules/ROOT/pages/observability.adoc
+++ b/docs/modules/ROOT/pages/observability.adoc
@@ -0,0 +1,8 @@
+[[observability]]
+= Observability
+
+== Observability metadata
+
+include::partial$_metrics.adoc[]
+
+include::partial$_spans.adoc[]
--- a/docs/modules/ROOT/pages/preface.adoc
+++ b/docs/modules/ROOT/pages/preface.adoc
@@ -7,10 +7,11 @@ This section provides a brief overview of the Spring Cloud Task reference docume
 Think of it as a map for the rest of the document. You can read this reference guide in a
 linear fashion or you can skip sections if something does not interest you.

+[[about-the-documentation]]
 == About the documentation
-The Spring Cloud Task reference guide is available in {spring-cloud-task-docs}[html] 
-and {spring-cloud-task-docs}/index.pdf[pdf]. The latest copy is available at
-{spring-cloud-task-docs-current}.
+The Spring Cloud Task reference guide is available in https://docs.spring.io/spring-cloud-task/docs/current/reference[html].
+The latest copy is available at
+https://docs.spring.io/spring-cloud-task/docs/current-SNAPSHOT/reference/html/.

 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
@@ -32,14 +33,14 @@ involved].
 [[task-documentation-first-steps]]
 == First Steps
 If you are just getting started with Spring Cloud Task or with 'Spring' in general, we
-suggesting reading the <<getting-started.adoc#getting-started>> chapter.
+suggesting reading the xref:getting-started.adoc[Getting started] chapter.

 To get started from scratch, read the following sections:

-* <<getting-started.adoc#getting-started-introducing-spring-cloud-task, Introducing Spring Cloud Task>>
-* <<getting-started.adoc#getting-started-system-requirements, System Requirements>> +
+* xref:getting-started.adoc#getting-started-introducing-spring-cloud-task[Introducing Spring Cloud Task]
+* xref:getting-started.adoc#getting-started-system-requirements[System Requirements] +

 To follow the tutorial, read
-<<getting-started.adoc#getting-started-developing-first-task, Developing Your First Spring Cloud Task Application>> +
+xref:getting-started.adoc#getting-started-developing-first-task[Developing Your First Spring Cloud Task Application] +
 To run your example, read
-<<getting-started.adoc#getting-started-running-the-example, Running the Example>>
+xref:getting-started.adoc#getting-started-running-the-example[Running the Example]
--- a/docs/modules/ROOT/pages/spring-cloud-task.adoc
+++ b/docs/modules/ROOT/pages/spring-cloud-task.adoc
@@ -1,7 +1,8 @@
+[[spring-cloud-task-reference-guide]]
 = Spring Cloud Task Reference Guide
+:page-section-summary-toc: 1
 Michael Minella, Glenn Renfro, Jay Bryant

-include::_attributes.adoc[]

 // ======================================================================================

@@ -14,18 +15,11 @@ 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.

-include::preface.adoc[]

-include::getting-started.adoc[]

-include::features.adoc[]

-include::batch.adoc[]

-include::batch-starter.adoc[]

-include::stream.adoc[]

-include::appendix.adoc[]

 // ======================================================================================
--- a/docs/modules/ROOT/pages/stream.adoc
+++ b/docs/modules/ROOT/pages/stream.adoc
@@ -162,6 +162,7 @@ NOTE: A sample batch event application can be found in the samples module
 of the Spring Cloud Task Project,
 https://github.com/spring-cloud/spring-cloud-task/tree/master/spring-cloud-task-samples/batch-events[here].

+[[sending-batch-events-to-different-channels]]
 === Sending Batch Events to Different Channels

 One of the options that Spring Cloud Task offers for batch events is the ability to alter
@@ -174,6 +175,7 @@ following configuration:

 `spring.cloud.task.batch.events.step-execution-events-binding-name=my-step-execution-events`

+[[disabling-batch-events]]
 === Disabling Batch Events
 To disable the listener functionality for all batch events, use the following
 configuration:
@@ -197,6 +199,7 @@ spring.cloud.task.batch.events.item-write.enabled=false
 spring.cloud.task.batch.events.skip.enabled=false
 ----

+[[emit-order-for-batch-events]]
 === Emit Order for Batch Events
 By default, batch events have `Ordered.LOWEST_PRECEDENCE`. To change this value (for
 example, to 5 ), use the following configuration:
--- a/docs/modules/ROOT/partials/_configprops.adoc
+++ b/docs/modules/ROOT/partials/_configprops.adoc
--- a/docs/modules/ROOT/partials/_conventions.adoc
+++ b/docs/modules/ROOT/partials/_conventions.adoc
@@ -0,0 +1,13 @@
+[[observability-conventions]]
+=== Observability - Conventions
+
+Below you can find a list of all `GlobalObservationConvention` and `ObservationConvention` declared by this project.
+
+.ObservationConvention implementations
+|===
+|ObservationConvention Class Name | Applicable ObservationContext Class Name
+|`org.springframework.cloud.task.listener.DefaultTaskExecutionObservationConvention`|`TaskExecutionObservationContext`
+|`org.springframework.cloud.task.listener.TaskExecutionObservationConvention`|`TaskExecutionObservationContext`
+|`org.springframework.cloud.task.configuration.observation.DefaultTaskObservationConvention`|`TaskObservationContext`
+|`org.springframework.cloud.task.configuration.observation.TaskObservationConvention`|`TaskObservationContext`
+|===
--- a/docs/modules/ROOT/partials/_metrics.adoc
+++ b/docs/modules/ROOT/partials/_metrics.adoc
@@ -0,0 +1,82 @@
+[[observability-metrics]]
+=== Observability - Metrics
+
+Below you can find a list of all metrics declared by this project.
+
+[[observability-metrics-task-active]]
+==== Task Active
+
+____
+Metrics created around a task execution.
+____
+
+
+**Metric name** `spring.cloud.task` (defined by convention class `org.springframework.cloud.task.listener.DefaultTaskExecutionObservationConvention`). **Type** `timer`.
+
+**Metric name** `spring.cloud.task.active` (defined by convention class `org.springframework.cloud.task.listener.DefaultTaskExecutionObservationConvention`). **Type** `long task timer`.
+
+
+IMPORTANT: KeyValues that are added after starting the Observation might be missing from the *.active metrics.
+
+
+IMPORTANT: Micrometer internally uses `nanoseconds` for the baseunit. However, each backend determines the actual baseunit. (i.e. Prometheus uses seconds)
+
+
+Fully qualified name of the enclosing class `org.springframework.cloud.task.listener.TaskExecutionObservation`.
+
+IMPORTANT: All tags must be prefixed with `spring.cloud.task` prefix!
+
+.Low cardinality Keys
+[cols="a,a"]
+|===
+|Name | Description
+|`spring.cloud.task.cf.app.id` _(required)_|App id for CF cloud.
+|`spring.cloud.task.cf.app.name` _(required)_|App name for CF cloud.
+|`spring.cloud.task.cf.app.version` _(required)_|App version for CF cloud.
+|`spring.cloud.task.cf.instance.index` _(required)_|Instance index for CF cloud.
+|`spring.cloud.task.cf.org.name` _(required)_|Organization Name for CF cloud.
+|`spring.cloud.task.cf.space.id` _(required)_|Space id for CF cloud.
+|`spring.cloud.task.cf.space.name` _(required)_|Space name for CF cloud.
+|`spring.cloud.task.execution.id` _(required)_|Task execution id.
+|`spring.cloud.task.exit.code` _(required)_|Task exit code.
+|`spring.cloud.task.external.execution.id` _(required)_|External execution id for task.
+|`spring.cloud.task.name` _(required)_|Task name measurement.
+|`spring.cloud.task.parent.execution.id` _(required)_|Task parent execution id.
+|`spring.cloud.task.status` _(required)_|task status. Can be either success or failure.
+|===
+
+
+
+[[observability-metrics-task-runner-observation]]
+==== Task Runner Observation
+
+____
+Observation created when a task runner is executed.
+____
+
+
+**Metric name** `spring.cloud.task.runner` (defined by convention class `org.springframework.cloud.task.configuration.observation.DefaultTaskObservationConvention`). **Type** `timer`.
+
+**Metric name** `spring.cloud.task.runner.active` (defined by convention class `org.springframework.cloud.task.configuration.observation.DefaultTaskObservationConvention`). **Type** `long task timer`.
+
+
+IMPORTANT: KeyValues that are added after starting the Observation might be missing from the *.active metrics.
+
+
+IMPORTANT: Micrometer internally uses `nanoseconds` for the baseunit. However, each backend determines the actual baseunit. (i.e. Prometheus uses seconds)
+
+
+Fully qualified name of the enclosing class `org.springframework.cloud.task.configuration.observation.TaskDocumentedObservation`.
+
+IMPORTANT: All tags must be prefixed with `spring.cloud.task` prefix!
+
+.Low cardinality Keys
+[cols="a,a"]
+|===
+|Name | Description
+|`spring.cloud.task.runner.bean-name` _(required)_|Name of the bean that was executed by Spring Cloud Task.
+|===
+
+
+
+
--- a/docs/modules/ROOT/partials/_spans.adoc
+++ b/docs/modules/ROOT/partials/_spans.adoc
@@ -0,0 +1,56 @@
+[[observability-spans]]
+=== Observability - Spans
+
+Below you can find a list of all spans declared by this project.
+
+[[observability-spans-task-active]]
+==== Task Active Span
+
+> Metrics created around a task execution.
+
+**Span name** `spring.cloud.task` (defined by convention class `org.springframework.cloud.task.listener.DefaultTaskExecutionObservationConvention`).
+
+Fully qualified name of the enclosing class `org.springframework.cloud.task.listener.TaskExecutionObservation`.
+
+IMPORTANT: All tags must be prefixed with `spring.cloud.task` prefix!
+
+.Tag Keys
+|===
+|Name | Description
+|`spring.cloud.task.cf.app.id` _(required)_|App id for CF cloud.
+|`spring.cloud.task.cf.app.name` _(required)_|App name for CF cloud.
+|`spring.cloud.task.cf.app.version` _(required)_|App version for CF cloud.
+|`spring.cloud.task.cf.instance.index` _(required)_|Instance index for CF cloud.
+|`spring.cloud.task.cf.org.name` _(required)_|Organization Name for CF cloud.
+|`spring.cloud.task.cf.space.id` _(required)_|Space id for CF cloud.
+|`spring.cloud.task.cf.space.name` _(required)_|Space name for CF cloud.
+|`spring.cloud.task.execution.id` _(required)_|Task execution id.
+|`spring.cloud.task.exit.code` _(required)_|Task exit code.
+|`spring.cloud.task.external.execution.id` _(required)_|External execution id for task.
+|`spring.cloud.task.name` _(required)_|Task name measurement.
+|`spring.cloud.task.parent.execution.id` _(required)_|Task parent execution id.
+|`spring.cloud.task.status` _(required)_|task status. Can be either success or failure.
+|===
+
+
+
+[[observability-spans-task-runner-observation]]
+==== Task Runner Observation Span
+
+> Observation created when a task runner is executed.
+
+**Span name** `spring.cloud.task.runner` (defined by convention class `org.springframework.cloud.task.configuration.observation.DefaultTaskObservationConvention`).
+
+Fully qualified name of the enclosing class `org.springframework.cloud.task.configuration.observation.TaskDocumentedObservation`.
+
+IMPORTANT: All tags must be prefixed with `spring.cloud.task` prefix!
+
+.Tag Keys
+|===
+|Name | Description
+|`spring.cloud.task.runner.bean-name` _(required)_|Name of the bean that was executed by Spring Cloud Task.
+|===
+
+
+
+
--- a/docs/pom.xml
+++ b/docs/pom.xml
@@ -1,26 +1,30 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+		 xmlns="http://maven.apache.org/POM/4.0.0"
+		 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
 	<modelVersion>4.0.0</modelVersion>
+	<groupId>org.springframework.cloud</groupId>
+	<artifactId>spring-cloud-task-docs</artifactId>
 	<parent>
 		<groupId>org.springframework.cloud</groupId>
 		<artifactId>spring-cloud-task-parent</artifactId>
 		<version>3.1.0-SNAPSHOT</version>
 	</parent>
-	<artifactId>spring-cloud-task-docs</artifactId>
+	<packaging>jar</packaging>
 	<name>Spring Cloud Task Docs</name>
 	<description>Spring Cloud Task Docs</description>
 	<properties>
 		<docs.main>spring-cloud-task</docs.main>
 		<main.basedir>${basedir}/..</main.basedir>
-		<configprops.inclusionPattern>spring.cloud.task.*</configprops.inclusionPattern>
-		<upload-docs-zip.phase>deploy</upload-docs-zip.phase>
-		<asciidoctorj.pdf.version>1.5.0-alpha.16</asciidoctorj.pdf.version>
+		<configprops.inclusionPattern>spring.cloud.*</configprops.inclusionPattern>
+		<!-- 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.0</micrometer-docs-generator.version>
-		<micrometer-docs-generator.inputPath>${maven.multiModuleProjectDirectory}/spring-cloud-task-core</micrometer-docs-generator.inputPath>
+		<micrometer-docs-generator.version>1.0.2</micrometer-docs-generator.version>
+		<micrometer-docs-generator.inputPath>${maven.multiModuleProjectDirectory}/spring-cloud-task-core/</micrometer-docs-generator.inputPath>
 		<micrometer-docs-generator.inclusionPattern>.*</micrometer-docs-generator.inclusionPattern>
-		<micrometer-docs-generator.outputPath>${maven.multiModuleProjectDirectory}/target/</micrometer-docs-generator.outputPath>
+		<micrometer-docs-generator.outputPath>${maven.multiModuleProjectDirectory}/docs/modules/ROOT/partials/</micrometer-docs-generator.outputPath>
 	</properties>
 	<dependencies>
 		<dependency>
@@ -41,31 +45,34 @@
 		<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.apache.maven.plugins</groupId>
 						<artifactId>maven-dependency-plugin</artifactId>
 					</plugin>
-					<plugin>
-						<artifactId>maven-resources-plugin</artifactId>
-					</plugin>
 					<plugin>
 						<groupId>org.codehaus.mojo</groupId>
 						<artifactId>exec-maven-plugin</artifactId>
+						<!-- TODO: Remove this execution if you have no observability -->
 						<executions>
 							<execution>
-								<id>generate-docs</id>
-								<phase>prepare-package</phase>
+								<id>generate-observability-docs</id>
+								<phase>${generate-docs.phase}</phase>
 								<goals>
 									<goal>java</goal>
 								</goals>
 								<configuration>
-									<mainClass>
-										io.micrometer.docs.DocsGeneratorCommand
-									</mainClass>
+									<mainClass>io.micrometer.docs.DocsGeneratorCommand</mainClass>
 									<includePluginDependencies>true</includePluginDependencies>
 									<arguments>
 										<argument>${micrometer-docs-generator.inputPath}</argument>
@@ -85,10 +92,15 @@
 						</dependencies>
 					</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>
 						<artifactId>maven-antrun-plugin</artifactId>
 						<executions>
 							<execution>
--- a/docs/src/main/antora/resources/antora-resources/antora.yml
+++ b/docs/src/main/antora/resources/antora-resources/antora.yml
@@ -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@
--- a/docs/src/main/asciidoc/README.adoc
+++ b/docs/src/main/asciidoc/README.adoc
@@ -1,3 +1,4 @@
+[[spring-cloud-task]]
 = Spring Cloud Task

 Is a project centered around the idea of processing on demand.  A user is able to develop
@@ -5,10 +6,12 @@ a “task” that can be deployed, executed and removed on demand, yet the resul
 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]
@@ -16,6 +19,7 @@ process persists beyond the life of the task for future reporting.
 $ ./mvnw clean install
 ----

+[[example:]]
 == Example:

 [source,java,indent=2]
@@ -43,9 +47,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 spring-code-of-conduct@pivotal.io.

+[[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.
--- a/docs/src/main/asciidoc/_observability.adoc
+++ b/docs/src/main/asciidoc/_observability.adoc
@@ -1,8 +0,0 @@
-:root-target: ../../../target/
-
-[[observability]]
-== Observability metadata
-
-include::{root-target}_metrics.adoc[]
-
-include::{root-target}_spans.adoc[]
--- a/docs/src/main/asciidoc/appendix.adoc
+++ b/docs/src/main/asciidoc/appendix.adoc
@@ -1,12 +0,0 @@
-
-[[appendix]]
-= Appendices
-
-include::appendix-task-repository-schema.adoc[]
-
-include::appendix-building-the-documentation.adoc[]
-
-ifndef::train-docs[]
-include::_observability.adoc[]
-endif::[]
-
--- a/docs/src/main/asciidoc/index.adoc
+++ b/docs/src/main/asciidoc/index.adoc
@@ -1 +0,0 @@
-include::spring-cloud-task.adoc[]