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
. The 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 docs
folder.
Note
|
More information about the antora.yml and the nav.adoc file can be found here and here, respectively.
|
In short, our documentation sources are expected to have at least the following structure:
docs βββ antora.yml βββ modules βββ ROOT βββ nav.adoc βββ pages βββ ...
The 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.
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 README.adoc
.
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 antora-playbook.yml
file.
Tip
|
The README.adoc of the customized Docker image contains a command that you can use to build the documentation pages locally to preview you changes.
|
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.
A good 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.
Tip
|
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). |
Youβll notice that the last sections of the README.adoc
that are automatically generated by Terraform Docs.
Everything that is between the comments BEGIN_TF_DOCS
/ END_TF_DOCS
and BEGIN_TF_TABLES
/ END_TF_TABLES
is generated automatically by a GitHub workflow, that is available in the main repository.