The autocppapi extension for listing Doxylink C++ APIs through Doxylink#

Documenteer provides an autocppapi directive that serves a similar role as automodapi, but instead provides a listing of APIs in a C++ namespace. The autocppapi works with Doxylink_ to link to APIs in a Doxygen site.

To use this directive, add the documenteer.ext.autocppapi extension to your conf.py file:

extensions = [..., "sphinxcontrib.doxylink", "documenteer.ext.autocppapi"]

Important

The autocppapi extension needs Doxylink to be installed and also included in the extensions listing. If you installed autocppapi through the “pipelines” extra, Doxylink will be installed for you. Doxylink is automatically configured in Pipelines documentation builds to point to a Doxygen site that’s embedded during the build process (see Overview of the pipelines.lsst.io build system). Otherwise, you can manually add Doxylink to your project’s depenencies:

pip install sphinxcontrib-doxylink

autocppapi directive#

.. autocppapi:: namespace#

Create a listing of APIs associated with the given namespace. The listing is broken into subsections for each type of API:

Classes
Structs
Variables
Defines

Each listed item is a link into the Doxygen C++ API reference.

Example

.. autocppapi:: lsst::afw::image

This example produces a listing of APIs associated with the lsst::afw::image namespace. In order to use autocppapi like this, without additional options, you need to set the documenteer_autocppapi_doxylink_role configuration value in your conf.py file.

Options

:doxylink-role: role-name: Set this option to the name of the Doxylink role instead of using the documenteer_autocppapi_doxylink_role configuration variable.

Configurations#

documenteer_autocppapi_doxylink_role

Set this configuration variable to the name of the Doxylink role. As an example, this is how pipelines.lsst.io configures the extension:

doxylink = {"lsstcc": ("_doxygen/doxygen.tag", "cpp-api")}

documenteer_autocppapi_doxylink_role = "lsstcc"

To override this configuration on a per-autocppapi directive basis, you can use the directive’s :doxylink-role: option instead.