Antora Guide

Antora

This tool renders the documentation for Boost modules whose documentation use asciidoc.

Installing Antora

Caution

The workflow may change in the future.

Dependencies

Antora requires Node.js:

$ node -v

This command should return an active Node.js LTS version number:

v16.18.0

If you have Node.js installed, but it isn’t an active LTS version, you need to upgrade Node.js.

$ nvm install --lts

Install Antora

After cloning the project, you need to install Antora command line interface (CLI) and the Antora site generator describe in the package.json file:

$ npm ci

Verify the antora command is now available by running:

$ npx antora -v

@antora/cli: 3.1.2
@antora/site-generator: 3.1.2

You also have the option of installing Antora globally so that the antora command is available on your PATH.

$ npm i -g @antora/[email protected] @antora/[email protected]

$ antora -v

@antora/cli: 3.1.2
@antora/site-generator: 3.1.2

Read more about antora on their Quickstart guide

Generating the website

The website is composed of components defined in the content.sources field of its playbook file site.playbook.yml. To generate the develop version of the website, run the Antora command with the following options:

npx antora --fetch --attribute boost_version=develop --attribute boost_site_prefix=develop/ site.playbook.yml

This should build the website in build/develop/doc/.

Important

Notice the --attribute options. Instead of using the Antora versioning control system, we render the documentation for a single version. To achieve this, we use an Antora extension that let us render the playbook for a single documentation version via these attributes. By setting --attribute boost_version=develop, the Antora playbook will fetch the develop branch of each documentation component.

To simplify the process of setting these attributes, you should use the sitedoc.sh script. Let us generate the develop and master versions of the documentation:

./sitedoc.sh develop
./sitedoc.sh master

Site generation complete!
Open file:///home/user/path/to/antora/build/develop/doc in a browser to view your site.
Site generation complete!
Open file:///home/user/path/to/antora/build/doc in a browser to view your site.

Generating the library documentation

The process for generating the documentation for all libraries is similar. Each library documentation is defined as a component in the playbook file libs.playbook.yml:

content:
  sources:
  - url: https://github.com/cppalliance/user-guide
    start_path: antora
  - url: https://github.com/vinniefalco/mp11
    start_path: antora
  # ...

To simplify the process of setting attributes, you should use the libdoc.sh script:

./libdoc.sh develop
./libdoc.sh master

Site generation complete!
Open file:///home/user/path/to/antora/build/develop/libs/index.html in a browser to view your site.
Site generation complete!
Open file:///home/user/path/to/antora/build/master/libs/index.html in a browser to view your site.

The complete libdoc.sh command syntax is:

Usage: ./libdoc.sh { branch | version | 'release' | 'all' }...

    branch : 'develop' | 'master' | 'release'
    version: [0-9]+ '.' [0-9]+ '.' [0-9]+
    'release': builds master to build/doc/html
    'all': rebuilds develop, master, and every version

Examples:

    ./libdoc.sh develop master      # build develop and master
    ./libdoc.sh 1.83.0              # build tagged version boost-1.83.0

The first positional argument is the only parameter, which identifies which version should be built.

• branch: valid arguments are master or develop. Builds the master or develop versions of the documentation in build/master/libs or build/develop/libs. It checks out all libraries in their master or develop branches.

• version: a semver version, such as 1.82.0 describing a Boost version. This allows us to generate the documentation content of an old Boost version with the current version of the Antora UI.

• 'release': generate the master version to build/doc/html with the release UI layout. This layout omits the header, Google analytics, and Edit this Page. This version of the documentation is meant to be distributed with sources files in the Boost release.

• 'all': retroactively iterate and generate the documentation for all versions of Boost with the most recent Antora UI. This command iterates each playbook in the history directory.

The master/develop branches of the library documentation are designed to co-exist alongside the per-release documentation and thus the branch name (or release version) does appear in its URLs.

Working on a single component

Each Antora-enabled library includes the component version descriptor file antora/antora.yml. Each library should contain an antora.yml describing the component. For instance,

name: mp11
title: Boost.Mp11
version: ~
nav:
  - modules/ROOT/nav.adoc

By checking antora/antora.yml and the modules directory into git, the repository is identified as an Antora content source, which can be listed in libs.playbook.yml of this repository. When working locally on an individual component, it’s the developers responsibility to adjust and maintain a local playbook.

Adjusting the local playbook

To render the documentation locally using the local filesystem. Modify and include a local version of lib.playbook.yml as local.playbook.yml for your repository.

Boost library candidates

When writing a Boost library proposal, include your library in the local playbook. For instance, supposed you are proposing a boost library installed in the boost/libs directory:

- url: /boost/libs/proposed-lib
  start_path: antora

Boost libraries

When working on an existing Boost library, the url field cannot be set to /path/to/boost/libs/my_library because the subdirectories of boost/libs are submodules. Instead, change the URL for one or more content sources to point to the boost superproject and adjust the start path accordingly:

- url: /path/to/boost
  start_path: libs/existing-lib/antora

This local version will include your repository only. Run npx antora --fetch playbook.yml and similar antora commands described above to build the docs.

• See https://docs.antora.org/antora/latest/install-and-run-quickstart/

• The output automatically goes in build/site/