Building Documentation with Antora

The standard is to use Asciidoc for authoring documentation and then building and publishing it with Antora. Documentation is built from the root project.

Adding the plugin

You can add the plugin via the traditional way

build.gradle

plugins {
  id 'org.ysb33r.ysf-project.docs.antora' version '0.0.8' (1)
}

Or you can add it with a version catalog

gradle/libs.versions.toml

[versions]
ysfProjectPlugin = "0.0.8"

[plugins]
ysfDocs = { id = "org.ysb33r.ysf-project.docs.antora", version.ref = "ysfProjectPlugin" }

build.gradle

plugins {
  alias(libs.plugins.ysfDocs)
}

Configuring documentation output

build.gradle

ysfProject {
  antora {
    title = 'Gradle Plugin Suite for Internal YSF Projects' (1)
    preserveLegacyDocumentation = false (2)
  }
}

1	A title for the documentation. Affects the TITLE substitution in `antora.yml
2	If you are upgrading a project that has older versions of published documentation, and you want to keep the documentation, set this to `true`, otherwise set it to `false`.

Creating antora.yml

The plugin adds a number of tokens which can be substituted. You can use a standard template for creating antora.yml

docs/antora.yml

name: "##COMPONENT##"
title: "##TITLE##"
version: "##VERSION##"
start_page: "##STARTDOC##"
nav:
  - modules/ROOT/nav.adoc
asciidoc:
  attributes:
    revnumber: "##VERSION##"

Table 1. Tokens in antora template
`COMPONENT`	The name of the component is normally derived from the root project name, but can be set via `ysfProject.antora.componentName`.
`TITLE`	Set via `ysfProject.antora.title`.
`VERSION`	Derived from the project version.
`MORE_NAVS`	Injected by the build to add more navigation files.
`ATTRIBUTES`	Some attributes are supplied by the build, but any van be added via `ysfProject.asciidoc.attributes`.

Preserving legacy documentation

If you are upgrading a project that has older versions of published documentation, you will probably want to keep that documentation. You need to take two extra steps BEFORE publishing any documentation - enable preservation and add a list of preserved versions.

Once you have turned off legacy preservation and published the documentation, you cannot later turn it on again. The documentation will be removed from the pages branch. Even though the links will be published, they will be broken.

Enable preservation

build.gradle

ysfProject {
  antora {
    preserveLegacyDocumentation = true
  }
}

List preserved versions.

You need to add a file docs/legacy-versions.txt. This is the same format as docs/display-versions.txt. The easiest way to create it is to move the old docs/landingPage/display-versions.txt and then renaming it.

docs/legacy-versions.txt

# These are versions that were listed when we build documentation the old landinge page way.
#
0.0.0.1

Testing documentation

You can build documentation locally by running the assembleDocumentation task. This will place content in build/docs/test-docs. It will only contain the current version’s documentation, but it is the quickest way to proofread your documentation in a rendered way.

Build all versions locally

In order to build and view all documents locally, the build needs to have access to the cloud Git repository. You need to provide two system properties and one Gradle property (the latter can be a system property too).

org.ajoberstar.grgit.auth.username - Git repository username.
org.ajoberstar.grgit.auth.password - Git repository token.
ci.project.url - Project URL of your project.

You can run the build as follows.

./gradlew -Dorg.ajoberstar.grgit.auth.username=YOUR_USER -Dorg.ajoberstar.grgit.auth.password=YOUR_TOKEN \
  -Pci.project.url=$(git remote -v | head -1 | awk '{print $2;}' | sed -e 's|\.git||') \
  antoraBuildLocalDocs

Combining Nav entries into one

In order to work around a yet-to-be-solved-issue in Antora, the build will append all generated navigation files to the ROOT/nav.adoc file.

To turn off this behaviour set the property `org.ysb33r.ysf.projects.antora.combine-navs=false' in `gradle.properties.

If you need to exclude artifact navigation for some reason the set the property org.ysb33r.ysf.projects.antora.include-artifact-navs=false in gradle.properties.