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

Warning

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:

Use the lsstcc role to link to a C++ API in the Doxygen subsite.

Link to a class:

:lsstcc:`lsst::afw::table::Schema`

Link to a method:

:lsstcc:`lsst::afw::table::Schema::getRecordSize`

Overloaded functions must be linked with their full signature. In that case, escape any angle brackes with a backslash (< → \< and > → \>):

:lsstcc:`lsst::afw::table::KeyBase\< Flag \>`

Tip

By default, the stack-docs listcc command shows escaped API signatures, ready to copy and paste into an lsstcc role.

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):

  :lsstcc:`lsst::afw::table::Schema <Schema>`

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 lsstcc role. 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:

stack-docs listcc

You filter the signatures with a regular expression pattern. To filter only the lsst::afw::table APIs:

stack-docs listcc -p lsst::afw::table

The -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 -t options. To see both classes and functions:

stack-docs listcc -t class -t function

The available types are:

• class

• define

• enumeration

• file

• function

• group

• namespace

• struct

• typedef

• variable

See also

For more information, see the reference documentation for the stack-docs command.