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...
    "sphinx_immaterial.apidoc.cpp.external_cpp_references",
]

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.

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.