External C++ symbol links

This theme includes an optional sphinx_immaterial.apidoc.cpp.external_cpp_references extension that allows normal C++ symbol references, e.g. through the cpp:expr role or in C++ function signatures, to resolve to externally-defined C++ symbols that are manually specified in conf.py. Unlike the sphinx.ext.intersphinx extension, template arguments are stripped when resolving references, which allows template entities to be resolved based on their base name.

To use this extension, add it to the list of extensions in conf.py and define the external_cpp_references configuration option:

extensions = [
    # other extensions...
external_cpp_references = {
    "nlohmann::json": {
        "url": "https://json.nlohmann.me/api/json/",
        "object_type": "type alias",
        "desc": "C++ type alias",
    "nlohmann::basic_json": {
        "url": "https://json.nlohmann.me/api/basic_json/",
        "object_type": "class",
        "desc": "C++ class",
.. cpp:function:: int ExtractValueFromJson(::nlohmann::json json_value);

    Extracts a value from a JSON object.
int ExtractValueFromJson(::nlohmann::json json_value);

Extracts a value from a JSON object.

external_cpp_references : dict[str, ExternalCppReference] = {}

A dictionary specifying the URL, object type, and descriptive text for each externally documented symbol name.

class sphinx_immaterial.apidoc.cpp.external_cpp_references.ExternalCppReference[source]

Bases: TypedDict

A class used to represent each dictionary field’s value specified in external_cpp_references.

desc : str

Description text to include in the tooltip.

object_type : str

C++ object type. This should be one of the object types defined by the C++ domain:

  • "class"

  • "union"

  • "function"

  • "member"

  • "type"

  • "concept"

  • "enum"

  • "enumerator"

url : str

URL to use as the target for references to this symbol.

Last update: Sep 16, 2023