Cross-linking the Doxygen-built C++ API reference with the lsstcc role
The pipelines.lsst.io project includes an embedded Doxygen -generated subsite to document the LSST Science Pipelines’s C++ API.
For more information about the Doxygen subsite, see Doxygen build from the pipelines.lsst.io build overview.
This page describes how to link between reStructuredText content and the C++ API reference.
Link to C++ APIs with the lsstcc role
The Sphinx configuration for the pipelines.lsst.io project includes a special
lsstcc role that replaces the use of Sphinx’s native domain cross links (the single backtick syntax).
Some of LSST’s C++ APIs are not compatible with doxylink.
In particular, method that use the
noexcept operator, are
operator(), or use macros like
PTR, don’t seem to be linkable with doxylink 1.6.
Use the stack-docs listcc command to identify linkable API signatures.
As a last resort, you may want to manually create a relative hyperlink.
Contact #dm-docs on Slack for help.
lsstcc role to link to a C++ API in the Doxygen subsite.
Link to a class:
Link to a method:
Overloaded functions must be linked with their full signature.
In that case, escape any angle brackes with a backslash (
:lsstcc:`lsst::afw::table::KeyBase\< Flag \>`
By default, the stack-docs listcc command shows escaped API signatures, ready to copy and paste into an
You can customized the displayed test of the API link by enclosing the displayed test in angle brackets (that’s why you need to escape angle brackets in signatures):
In the above example, the linked text will be "Schema."
The ``~`` prefix, used in Python domain links, does not work with the ``lsstcc`` role; using angle brackets to explicitly rename a link lets you achieve the same result.
Listing linkable C++ APIs (stack-docs listcc)
Documenteer includes the stack-docs listcc command that helps you find C++ APIs that are linkable with the
The APIs are automatically escaped so that you can copy-and-paste them into the
lsstcc role in a reStructuredText document.
From the pipelines_lsst_io project repository, run the command to see the signatures of all available APIs:
You filter the signatures with a regular expression pattern.
To filter only the
stack-docs listcc -p lsst::afw::table
-p optional accepts any Python regular expression syntax.
Additionally, you can also filter by type.
For example, to see only header files:
stack-docs listcc -t file
You can supply multiple
To see both classes and functions:
stack-docs listcc -t class -t function
The available types are:
For more information, see the reference documentation for the stack-docs command.