C++ Reference Extension for Antora
npm install @cppalliance/antora-cpp-reference-extensionInstall this extension
`` bash`
npm i -D @cppalliance/antora-cpp-reference-extension
Before building the Antora playbook, make sure you have the following
installed:
-
- 7z (Windows) or tar (Linux)
- git
Append the following in your playbook.yaml:
` yaml`
antora:
extensions:
- require: '@cppalliance/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:@cppalliance/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, thevariable
extension will set the value of 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 | * |allow-master
| | specifies the version | |
| | of MrDocs to use. | |
+-----------------------+-----------------------+-----------------------+
| | If true, the | true |master
| | extension will allow | |
| | the use of the | |
| | branch for | |version
| | MrDocs if | |*
| | is . | |allow-develop
+-----------------------+-----------------------+-----------------------+
| | If true, the | true |develop
| | extension will allow | |
| | the use of the | |
| | branch for | |version
| | MrDocs if | |*
| | is . | |module
+-----------------------+-----------------------+-----------------------+
| | Antora module that | reference |modu | |
| | will receive the | |
| | generated pages | |
| | (
| | les/). | |
+-----------------------+-----------------------+-----------------------+
Components that will include reference documentation should set the path
of the MrDocs configuration file. Append following in your
antora.yaml:
` yaml`
ext:
cpp-reference:
config: doc/mrdocs.yml #
module: api-ref #
- \<1\> The path to the MrDocs configuration file relative to the
worktree.
- \<2\> (Optional) Override the Antora module used for the generated
pages. If omitted the component inherits the module set at the
playbook level (or reference when neither level specifies a
value).
For more information about MrDocs, see
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:
` asciidoc`
* xref:reference:index.adoc[Reference]
When the tagfiles extension
(
listed in your playbook, the reference tagfile is registered
automatically and picked up within the same Antora run---even if you
change the module name.
` yaml`
antora:
extensions:
- require: '@cppalliance/antora-cpp-reference-extension'
- require: '@cppalliance/antora-cpp-tagfiles-extension'
With this configuration, you don't need to copy tagfiles into your
repository or commit them to source control to satisfy cpp: macros.
The example` directory contains an example project with a component
that uses the extension.