How does Antora work?
Antora builds this documentation website from the configurations in an Antora Playbook, which is a YAML file that describes the documentation sources and the output of the build.
Our playbook is stored on the root of the main repository of the DevOps Stack project, in the
antora-playbook.yml file. It is this file that defines the content sources (in our case each module of the DevOps Stack project) as well as the tags to take into account when building the documentation.
In this file you’ll see a source for the main documentation (that is, the more generic pages stored in the main repository) and sources for each module on a list under
content.sources. Each source is defined by a
url to its repo and a
start_path that tells Antora where the respective documentation is stored.
Each documentation source is expected to have a precise file structure, as documented in extensive detail in the Antora documentation.
In short, the documentation source is expected to have a
antora.yml file at its root, a
modules folder that contains the documentation modules and a
nav.adoc file is used to generate the navigation menu on the left of the documentation website and the documentation pages are used to generate the content of the website. You’ll see this folder structure throughout our modules inside the
More information about the
In short, our documentation sources are expected to have at least the following structure:
docs ├── antora.yml └── modules └── ROOT ├── nav.adoc └── pages └── ...
antora.yml for each module is quite simple:
--- name: "<MODULE_NAME>" # The name of the module that will appear in the URL of the generated documentation, use something short. title: "<MODULE_NAME>" # The title of the module that will appear in the navigation menu of the generated documentation. version: true # Tells Antora to use the version tag of the module as the version of the documentation. start_page: README.adoc # Tells Antora which page to use as the start page of this module's documentation. nav: - "modules/ROOT/nav.adoc" # Tells Antora which navigation file to use for this module's documentation.
Each module’s documentation page is versioned using its repository tags, which are automatically created by the Release Please CI. On each source of our Antora playbook, we can define which version tags we include or exclude using the syntax explained here.
In our case, note that we chose to use the tags instead of the branches for versioning the document pages. This is because we release each new version on a single branch but through multiple tags. More explanations about the different versioning methods are available here.
Building the documentation
Our documentation is built using a GitHub Action on the main repository, available here.
In the workflow, you will note that our documentation is generated using a customized Docker image of Antora. This is because we require two extensions on top of Antora, as explained in the
README.adoc. The release process of this image is also explained on said
The UI of the documentation pages comes from a fork of the default Antora UI, available here. This fork is used to add a custom syntax highlighter for Terraform code blocks. In order to use this UI, we simply create a
*.zip bundle with a GitHub Actions workflow that is then pointed to by our
After generating the documentation, it is then published to the
gh-pages branch of the main repository. This branch is then used by GitHub Pages to serve the documentation website.
The documentation in each module is quite particular in the sense that we have not put the documentation pages on the
docs folder. Instead we have symbolic links to the
README.adoc on the root of the repository and to the
README.adoc inside each variant. Consequently, a typical module as a structure like this:
devops-stack-module-template └── docs ├── antora.yml └── modules └── ROOT ├── nav.adoc └── pages ├── aks │ └── README.adoc -> ../../../../../aks/README.adoc ├── eks │ └── README.adoc -> ../../../../../eks/README.adoc ├── kind │ └── README.adoc -> ../../../../../kind/README.adoc └── README.adoc -> ../../../../README.adoc
As you can see, besides the root
README.adoc, each variant should have its own file. This is because of the way the automatic documentation is generated (Terraform Docs needs to put the generated documentation on separate files) and since each variant has its own specificities.
A simple module without variants has a simpler structure:
devops-stack-module-template └── docs ├── antora.yml └── modules └── ROOT ├── nav.adoc └── pages └── README.adoc -> ../../../../README.adoc
The module template contains a good example of what the
README.adoc should include in its content.
README.adoc should contain a small description of what the module does and, if it installs a chart, list the chart version along with a link to the official chart and documentation. Next, show some examples of the usage of the module, from the simplest to the most complex. Finally, the end of the module will contain the automatic documentation.
A module that has variants will be a bit different. The main
README.adoc should contain an introduction and chart version, but it is each variant’s
README.adoc that should have usage examples, as these are different from variant to variant.
|Check the existing module’s documentation pages for examples (the Thanos module is a good example of a module with variants and the Keycloak module is an example without).|
Terraform Docs documentation
You’ll notice that the last sections of the
README.adoc that are automatically generated by Terraform Docs.
Everything that is between the comments
END_TF_TABLES is generated automatically by a GitHub workflow, that is available in the main repository.