C++ domain customization

cpp_strip_namespaces_from_signatures : list[str] = []

list[str] specifying namespaces to strip from signatures. This does not apply to the name of the symbol being defined by the signature, only to parameter types, return types, default value expressions, etc.

For example, with the following in conf.py:

cpp_strip_namespaces_from_signatures = [
    "my_ns1",
    "my_ns2",
    "my_ns2::my_nested_ns",
]
C++ function definition with stripped namespaces
.. cpp:type:: my_ns1::A

.. cpp:type:: my_ns2::my_nested_ns::B

.. cpp:type:: my_ns3::C

.. cpp:function:: void my_ns1::MyFunction(my_ns1::A x, my_ns2::my_nested_ns::B y, my_ns3::C);
type my_ns1::A
type my_ns2::my_nested_ns::B
type my_ns3::C
void my_ns1::MyFunction(A x, B y, my_ns3::C);

Warning

If a nested symbol name like "my_ns1::abc" is specified in cpp_strip_namespaces_from_signatures, then a reference like my_ns1::abc::X will be converted to my_ns1::X. To also strip the my_ns1:: portion, "my_ns1" must also be specified in cpp_strip_namespaces_from_signatures.

cpp_xref_resolve_c_macro_pattern : str = '[A-Z]+[A-Z_0-9]*'

This theme adds support for resolving C macros and C macro parameters from cross references created using C++-domain roles like cpp:expr and cpp:texpr.

To avoid an additional symbol lookup in most cases, this support relies on a regular expression pattern to identify potential C macro targets. By default, only names consisting of uppercase latin letters, underscores, or digits are supported. To support macros with other names, this pattern may be changed:

Add to conf.py to allow all identifiers as macro names
cpp_xref_resolve_c_macro_pattern = "[^<>():]+"

#include directives in signatures

This theme extend the C and C++ domains to allow signatures to specify required #include directives.

Specifying #include directives in signatures
.. cpp:function:: #include "my_header.h"
                  #include "another_header.h"
                  void foo(int param);

   Some function.
#include "my_header.h"
#include "another_header.h"
void foo(int param);

Some function.

This theme extends the Sphinx C and C++ domain with support for the following options.

These options are primarily intended for use by other extensions, such as sphinx_immaterial.apidoc.cpp.apigen, rather than direct use by users.

:noindex:

Prevents the creation of a cross-reference target. Also excludes the object from search results.

Function defined with noindex option.
.. cpp:function:: int my_function(int x);

   Function defined once.

.. cpp:function:: int my_function(int x);
   :noindex:

   Function defined again.
int my_function(int x);

Function defined once.

int my_function(int x);

Function defined again.

Warning

Currently, due to how parameters are cross linked, there must be at least one definition of the object for which :noindex: is not specified.

See also

Sphinx itself supports the related :noindexentry: option, which prevents inclusion of the object in the “general index” (not normally useful with this theme anyway). A cross-reference target is still created, and the object still appears in search results.

:symbol-ids:

By default, every C++ signature is assigned a symbol identifier automatically based on its definition (similar to the name mangling scheme used by C++ compilers).

The :symbol-ids: option may be used to specify an alternative identifier for each signature.

Function defined with alternative symbol identifier.
.. cpp:function:: int my_function_with_custom_identifier(int x);
   :symbol-ids: ["my_custom_id"]
int my_function_with_custom_identifier(int x);

Warning

If the :symbol-ids: option is used to specify a symbol identifier that does not match [a-zA-Z0-9_]*, then :node-id: must also be used to specify an alternative valid HTML fragment identifier.

:node-id:

The node id is the HTML fragment identifier that is used to link to a given signature within a document. By default, the node id is the same as the symbol identifier, which may be redundant if the document only defines a single signature.

The :node-id: may be used to specify an alternative HTML fragment identifier. This option has no effect if :noindex: is also specified.

Function with alternative HTML fragment identifier
.. cpp:function:: int my_function_with_custom_fragment_identifier(int x);
   :node-id: custom_fragment_id

   Hover over the permalink symbol to see the custom fragment identifier.
int my_function_with_custom_fragment_identifier(int x);

Hover over the permalink symbol to see the custom fragment identifier.

Last update: Apr 16, 2024