Antora Guide

Antora requires Node.js:

This command should return the Node.js version number:

Antora requires Node.js version 16 or later. If you have Node.js installed but need to upgrade it:

The following instructions also require Git to clone the repository:

This command should return the Git version number:

To clone the repository that defines the Antora playbook for the Boost documentation:

This command clones the repository into a directory named website-v2-docs. This directory contains the Antora playbook files site.playbook.yml (website documentation) and libs.playbook.yml (library documentation).

After cloning the project, you need to install its dependencies using the Node.js package manager, npm:

Then build the Antora UI bundle used for the documentation:

The npx command, which comes with npm, can be used to build any of the playbooks in the repository.

Or to build the website documentation:

This commands will build the documentation in the build/ directory.

npx will download the Antora CLI and the Antora site generator, and then run the antora command with the specified playbook. These dependencies are cached locally, so the next time you run npx antora, it will be faster.

In the release process, Antora is called with extra attributes used by the documentation components. For instance:

The libdoc.sh script simplifies the process by building the UI bundle, identifying these attributes, and running the Antora command with the specified playbook.

Or to build the website documentation:

The build.sh script identifies the branch of the current repository and runs the sitedoc.sh script with the branch name as an argument:

Although not necessary, you also have the option of installing Antora globally so that the antora command is available on your PATH.

Read more about antora on their Quickstart guide.

The @cppalliance/antora-cpp-tagfiles-extension extension allows components to include links to C++ symbols defined in the library or external libraries.

For instance, std::string will generate a link to the std::string symbol in the documentation. Note that after the cpp: prefix from custom inline macros, the syntax is similar to the one used to generate regular links in AsciiDoc, where the link is replaced by the symbol name.

The link for each symbol is generated from a tagfile provided by the main playbook or by the extension. The playbook can define tagfiles for other libraries by including the cpp-tagfiles field in the extension configuration:

Note that the files field is a list of tagfiles that are used to generate links to symbols in the documentation. These tagfiles can be generated by other tools like Doxygen or MrDocs. In some cases, users might want to write their own tagfiles to include symbols from other libraries. As tagfiles only describe relative links to symbols, the base_url field is used to generate the full URL to the symbol.

Also note the using-namespaces field, which is a list of namespaces that are used to generate links to symbols in the documentation. In the example above, small_vector will generate a link to the boost::small_vector symbol in the documentation unless there’s a tagfile that defines a symbol with the same name in the global namespace.

Each component can also define its own tagfiles by including the cpp-tagfiles field in the component descriptor file:

Files and namespaces defined in components are only applied to that component.

More information about the extension can be found in its repository and issues should be reported in its issue tracker.

The @cppalliance/antora-cpp-reference-extension extension generates reference documentation for C++ symbols in your codebase and creates an Antora module with its pages. The asciidoc documentation pages are generated with MrDocs and populated in the reference Antora module.

This means, the generated reference pages can be linked in your doc/modules/ROOT/nav.adoc file as:

To enable the extension for your component, include the extension configuration in the antora.yml file:

The mrdocs.yml file will typically include parameters to generate a compile_commands.json file used to generate the reference documentation. For more information about MrDocs and configuration files, see https://www.mrdocs.com/docs.

The process to generate compile_commands.json typically depends on third-party libraries used to compile the project. In the case of Boost libraries, other Boost libraries should be available to the command that generates the compile_commands.json file. The dependencies available to components are defined in the libs.playbook.yml file.

The extension will download each dependency defined in this list and expose it to the MrDocs environment via the environment variable defined in variable. If the library is already available in the system, the system-env field can be used to expose it to Antora, so it uses this existing path instead of downloading the library.

More information about the extension can be found in its repository and issues should be reported in its issue tracker.

The @cppalliance/asciidoctor-boost-links extension allows component pages to include links to Boost libraries and tools. For instance:

This will render as if the equivalent AsciiDoc code was used:

When processed by Asciidoc, this renders as "Boost.Core":

The extension supports Boost libraries and tools. When no custom text is provided, the extension will use the library name in PascalCase as the link text. When a Boost author has a preference for a different default link text, these are implemented directly in the extension.

More information about the extension can be found in its repository and issues should be reported in its issue tracker.

The @cppalliance/antora-playbook-macros-extension extension allows playbooks to include macros that can be used to generate content in the playbook. Each macro has a default value that can be overridden with environment variables, the Antora --attribute command line option, or directly in the playbook with the asciidoc.attributes field.

The macro is used to implement the branch functionality described in section Running Antora. More information about the extension can be found in its repository and issues should be reported in its issue tracker.