Antora C++ Reference Extension

This extension generates reference documentation for C++ symbols in your codebase and creates an Antora module with its pages.

This extension populates the Antora pages with a reference module that contains the reference documentation for the C++ symbols in your codebase.

Configuration

npm

Install this extension

npm i -D @alandefreitas/antora-cpp-reference-extension

Requirements

Before building the Antora playbook, make sure you have the following installed:

• A C++ compiler (preferably Clang)

• 7z (Windows) or tar (Linux)

• git

Playbook

Append the following in your playbook.yaml:

antora:
  extensions:
    - require: '@alandefreitas/antora-cpp-reference-extension' # (1)
      dependencies: # (2)
        - name: 'boost'
          repo: 'https://github.com/boostorg/boost.git'
          tag: 'develop'
          variable: 'BOOST_SRC_ROOT'
          system-env: 'BOOST_SRC_ROOT' # (3)

• <1> npm package name: @alandefreitas/antora-cpp-reference-extension (required)

• <2> List of dependencies to be downloaded and extracted. The directory where these dependencies are extracted will be available to all components as an environment variable.

• <3> The name of the environment variable describing where the path can be found. If this path exists and is a valid directory, it will be used as the source root for the dependency, skipping the download and extraction steps. If this is different from variable, the extension will set the value of variable to the path where the dependency is already located.

Besides the dependencies configuration, you can also set the following options:

Option	Description	Default
version	A semver range that specifies the version of MrDocs to use.	*
allow-master	If true, the extension will allow the use of the master branch for MrDocs if version is *.	true
allow-develop	If true, the extension will allow the use of the develop branch for MrDocs if version is *.	true

Components

Components that will include reference documentation should set the path of the MrDocs configuration file. Append following in your antora.yaml:

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

• <1> The path to the MrDocs configuration file relative to the worktree.

For more information about MrDocs, see https://www.mrdocs.com/docs

References in the component

To include links to the reference module, the prefix xref:reference: should be used.

You would usually include a link to the main reference page in the component’s nav.adoc:

* xref:reference:index.adoc[Reference]

Example

The example directory contains an example project with a component that uses the extension.