@alandefreitas/antora-cpp-reference-extension v0.0.3
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 {#_configuration}
npm {#_npm}
Install this extension
npm i -D @alandefreitas/antora-cpp-reference-extension
Requirements {#_requirements}
Before building the Antora playbook, make sure you have the following installed:
A C++ compiler (preferably Clang)
7z
(Windows) ortar
(Linux)git
Playbook {#_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 ofvariable
to the path where the dependency is already located.
Components {#_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 {#_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 {#_example}
The example
directory contains an example project with a component
that uses the extension.