@cppalliance/antora-cpp-reference-extension

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:

• 7z (Windows) or tar (Linux)

• git

Playbook

Append the following in your playbook.yaml:

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

• <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 | true | | | extension will allow | | | | the use of the | | | | master branch for | | | | MrDocs if version | | | | is *. | | +-----------------------+-----------------------+-----------------------+ | allow-develop | If true, the | true | | | extension will allow | | | | the use of the | | | | develop branch for | | | | MrDocs if version | | | | is *. | | +-----------------------+-----------------------+-----------------------+

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