External C++ symbol links¶

This theme includes an optional sphinx_immaterial.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.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] = {}¶

Specifies for each symbol name a dictionary specifying the URL, object type, and description type:

class ExternalCppReference(typing.TypedDict):
    url: str
    object_type: str
    desc: str

The object_type should be one of the object types defined by the C++ domain:

• "class"

• "union"

• "function"

• "member"

• "type"

• "concept"

• "enum"

• "enumerator"