The ODS Antora Playbook Repository

Building documentation locally

Prerequisites

• Antora (3.1) has to be installed according to the Install Antora guide.

• The following OpenDevStack repositories have to be cloned and stored beside the ods-documentation repository: ods-core, ods-jenkins-shared-library, ods-provisioning-app and ods-quickstarters.

Generate docs using site-workspace.yml

To preview your local changes, just building documentation from HEAD.

antora generate site-workspace.yml

The output will be written to docs_local, which is ignored by git. This directory is only for local preview and verification.

Generate docs using site-workspace-full.yml

To preview your local changes, taking into account all branches.

antora generate site-workspace-full.yml

The output will be written to docs_local, which is ignored by git. This directory is only for local preview and verification.

Note that for this playbook, you will also need the following repositories locally:

• opendevstack.github.io

• ods-project-quickstarters

Customize the UI

By default, the playbooks reference a UI bundle from https://github.com/opendevstack/ods-docs-ui/releases. You can also clone that repo locally, customize the UI, build a new UI bundle and reference that when running antora.

To build a UI bundle, read the documentation at https://github.com/opendevstack/ods-docs-ui/blob/ods-docs-ui/README.adoc. Example:

cd ../ods-docs-ui
# Compile
npm install
# Create file ui-bundle.zip
gulp bundle
# Reference it
cd ../ods-documentation
antora generate site-workspace.yml --ui-bundle-url ../ods-docs-ui/build/ui-bundle.zip

Search Function

A search index is created by the antora lunr extension.

Building using GitHub Actions

Whenever this repository is pushed to GitHub, it triggers a build using GitHub Actions, that regenerates the antora documentation based on the site.yml playbook (which fetches the different referenced repositories from GitHub). The updated content in directory docs will be pushed back to the GitHub repository during the build. The build environment uses the GitHub Token (env: GITHUB_TOKEN) with write privileges to the repository.

See .github/workflows/renderDocs.yml for details.