Skip to content

Latest commit

 

History

History
467 lines (350 loc) · 17.3 KB

README.adoc

File metadata and controls

467 lines (350 loc) · 17.3 KB
Raw

Antora Guide

Antora

 https://antora.org/[Antora] is a static site generator designed for creating documentation sites from AsciiDoc content.
The tool renders the documentation for Boost modules whose documentation are defined as components in the Antora playbook.

Installing Antora

Dependencies

Antora requires Node.js:

$ node -v

This command should return the Node.js version number:

v16.18.0

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

$ nvm install --lts

The following instructions also require Git to clone the repository:

$ git --version

This command should return the Git version number:

git version 2.25.1

Cloning the repository

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

$ git clone https://www.github.com/boostorg/website-v2-docs

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).

Running Antora

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

$ npm ci

Then build the Antora UI bundle used for the documentation:

$ cd antora-ui
$ npx gulp
$ cd ..

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

$ npx antora --fetch libs.playbook.yml

Or to build the website documentation:

$ npx antora --fetch site.playbook.yml

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:

$ npx antora --fetch --attribute page-boost-branch=master --attribute page-boost-ui-branch=master --attribute page-commit-id=151c2ac libs.playbook.yml
Important

Instead of using the Antora versioning control system, we render the documentation for a single version by setting version: ~ in the antora.yml file. The --attribute options let us render the playbook for a single documentation version with context about the current version.

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

$ ./libdoc.sh master

Or to build the website documentation:

$ ./sitedoc.sh master
Site generation complete!
Open file:///home/user/path/to/antora/build/master/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.

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

$ ./build.sh

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

$ npm i -g @antora/cli @antora/site-generator
$ antora -v

Read more about antora on their Quickstart guide.

Playbook Components

The website is composed of components defined in the content.sources field of its playbook file site.playbook.yml. All components of the website are relative to the website-v2-docs repository.

The process for generating the documentation for all libraries is similar. However, the components are defined in the libs.playbook.yml file and their URLs are relative to the boostorg organization. Each library documentation is defined as a component in the playbook file libs.playbook.yml:

content:
  sources:
    - url: https://github.com/boostorg/url
      start_path: doc
  # ...

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.

Component Layout

Each Antora-enabled library includes the component version descriptor file doc/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

After defining the doc/antora.yml file, the source files should be organized in the modules directory. Typically, doc/modules/ROOT/nav.adoc is the main navigation file for the library documentation and doc/modules/ROOT/pages/index.adoc is the main page. You can find more information about the Component Version Descriptor and Pages in the Antora documentation.

Once these files are in place, the library can be registered as a component in the libs.playbook.yml file with a Pull Request to the website-v2-docs repository:

content:
  sources:
  # ...
    - <library-name>: https://github.com/boostorg/<library-name>
      start_path: doc

Local playbooks

When working locally on an individual component, it’s usually desirable to create a local playbook for your project so that you can render the documentation locally for a single component. The local playbook is a copy of the main playbook that removes all components except the one you are working on.

For instance, you can create a copy of libs.playbook.yml as doc/local-playbook.yml, remove all components except the one you are working on, and adjust the component URL to point to your local filesystem:

# ...
content:
  sources:
    - url: ..
      start_path: doc
      edit_url: 'https://github.com/boostorg/<library-name>/edit/{refname}/{path}'
# ...

This way, you can render the documentation locally for your component without having to render the entire Boost documentation:

$ npx antora --fetch local-playbook.yml

When writing a Boost library proposal, include your library in this local playbook.

Antora Extensions

Antora supports extensions that can be used to augment the functionality of the generator. The playbooks in the website-v2-docs repository include a number of extensions that are available to all components.

C++ Tagfiles Extension

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

For instance, cpp: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:

antora:
  extensions:
    # ...
    - require: '@cppalliance/antora-cpp-tagfiles-extension'
      cpp-tagfiles:
        files:
          - file: ./doc/tagfiles/boost-url-doxygen.tag.xml
            base_url: 'xref:reference:'
          - file: ./doc/tagfiles/boost-system-doxygen.tag.xml
            base_url: https://www.boost.org/doc/libs/master/libs/system/doc/html/
        using-namespaces:
          - 'boost::'
    # ...

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, cpp: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:

ext:
  cpp-tagfiles:
      files:
        - file: ./doc/tagfiles/boost-url-doxygen.tag.xml
          base_url: 'xref:reference:'
        - file: ./doc/tagfiles/boost-system-doxygen.tag.xml
          base_url: https://www.boost.org/doc/libs/master/libs/system/doc/html/
        - file: ./doc/tagfiles/boost-core-doxygen.tag.xml
          base_url: https://www.boost.org/doc/libs/master/libs/core/doc/html/
        - file: ./doc/tagfiles/boost-filesystem-doxygen.tag.xml
          base_url: https://www.boost.org/doc/libs/master/libs/filesystem/doc/
      using-namespaces:
        - boost::urls
        - boost::urls::grammar
        - boost::system
        - boost::core

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.

C++ Reference Extension

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:

// ...
* Reference
** xref:reference:index.adoc[]
// ...

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

# ...
ext:
  cpp-reference:
    config: doc/mrdocs.yml
# ...

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.

antora:
  extensions:
    - require: '@cppalliance/antora-cpp-reference-extension'
      dependencies:
        - name: 'boost'
          repo: 'https://github.com/boostorg/boost.git'
          tag: 'develop'
          variable: 'BOOST_SRC_DIR'
          system-env: 'BOOST_SRC_DIR'

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.

Boost Links Extension

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

boost:core[]

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

https://www.boost.org/libs/core[Boost.Core]

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

<a href="https://www.boost.org/libs/core">Boost.Core</a>

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.

Playbook Macros Extension

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.

Antora UI Bundle

Each Antora playbook includes a UI bundle that defines the layout of the documentation.

ui:
  bundle:
    url: ./antora-ui/build/ui-bundle.zip
    snapshot: true

This provides a consistent layout across all components of the playbook.

The source code for the UI bundle is located in the antora-ui directory of the repository.

The bundle includes a few options to customize the Boost UI by setting the following options in the main playbook:

asciidoc:
  attributes:
    # Enable pagination
    page-pagination: ''
    # Remove the sidenav and include TOC in index.adoc page
    remove-sidenav: ''
    # Include the contents panel with the TOC for the current page
    page-toc: ''

By default, all options are disabled. Setting the options to any string (including the empty string) enables it. This is a convention used by Antora to enable/disable options in bundles.

The settings defined in the playbook apply to all documentation components.

The UI bundle documentation is available in the antora-ui/README.adoc file. This file describes the structure of the UI bundle and how to customize it.