C++ API documentation generation¶

This theme includes an optional extension that generates C++ API documentation pages.

• The entities to document, along with their documentation, are extracted automatically from C/C++ header files using libclang. Doc comments are expected to be in reStructuredText syntax, although a limited set of Doxygen commands are also supported and converted automatically to their reStructuredText equivalents.

• A separate page is generated for each documented entity.

• Top-level module-level entities are organized into groups, specified by the :group: field within the docstring. The cpp-apigen-group directive is used to insert a summary of a group into an existing page.

• The summary of a group shows an abbreviated signature and an abbreviated description for each entity in the group; the name portion of the signature is a link to the separate page for that entity.

• Entities have three types of related entities:

  • Class members are automatically considered related members of their parent class.

  • Friend functions defined within a class definition (i.e. hidden friends) are also automatically considered related members of the containing class.

  • Any other entity may explicitly designate itself as a related non-member of any other entity using the :relates: field within the docstring.

  For a given parent entity, the related entities are also organized into groups, based on the :group: field within the related entities’ docstrings, as well as default group assignment rules. The summaries for each of these groups are included on the documentation page for the parent entity.

Usage¶

To use this extension, add "sphinx_immaterial.apidoc.cpp.apigen" to the list of extensions in conf.py and define the cpp_apigen_configs configuration option.

For example:

extensions = [
    # other extensions...
    "sphinx_immaterial.apidoc.cpp.apigen",
]

cpp_apigen_configs = {
    ...
}

This configuration is sufficient to generate a documentation page for every top-level member of the specified modules. To generate a listing of those top-level members and add the generated documentation pages to the global table of contents, the cpp-apigen-group directive may be used.

rST Directives¶

.. cpp-apigen-group:: group-name¶

Generates a summary of all top-level members that are in the specified group, and also inserts a table-of-contents entry for each member at the current document position.

Before matching the specified group name to the group name of every top-level member, all the group names are normalized by converting each letter to lowercase and converting spaces to -.

:notoc:¶

By default, this directive also adds the pages corresponding to the members of the specified group to the global table of contents as children of the current page/section. Specifying this flag disables that behavior.

Example usage¶

.. cpp-apigen-group:: indexing
   :notoc:

class cpp_apigen_demo::IndexInterval;

Demonstrates a non-template class.

.. cpp-apigen-entity-summary:: entity-name¶

Generates a summary of a single Python entity.

The entity-name should be specified as module_name.ClassName.member or module_name.ClassName.member(overload).

:notoc:¶

By default, this directive also adds the page corresponding to the specified Python entity to the global table of contents as a child of the current page/section. Specifying this flag disables that behavior.

Example usage¶

.. python-apigen-entity-summary:: tensorstore_demo.IndexDomain.__init__(json)
   :notoc:

tensorstore_demo.IndexDomain(*, json: Any)

Constructs an index domain from its JSON representation.

Configuration¶

cpp_apigen_configs : list[sphinx_immaterial.apidoc.cpp.apigen.ApigenConfig] = []¶

Specifies the C++ API parsing and documentation generation configurations to use.

class sphinx_immaterial.apidoc.cpp.apigen.ApigenConfig[source]¶

Specifies a C++ API generation configuration.

document_prefix: str¶

Sphinx document path prefix for the per-entity documentation pages.

Important

This should use the Linux path separator "/" (even if building on Windows).

api_parser_config: Config | None = None¶

Configuration for generating an API description.

This option and api_data are mutually exclusive.

api_data: str | None = None¶

Path to already-parsed API description.

This option and api_parser_config are mutually exclusive.

class sphinx_immaterial.apidoc.cpp.api_parser.Config[source]¶

Specifies a C++ API parsing configuration.

Based on this configuration, a description of the API is generated.

input_path: str = "__input.cpp"¶

Path to the input file to parse.

This may either be a path to an existing file, or input_content may specify its content, in which case the filesystem is not accessed.

If input_content is specified and merely contains #include directives, then the actual path does not matter and may be left as the default value.

input_content: bytes | None = None¶

Specifies the content of input_path.

If unspecified, the content is read from filesystem.

compiler_flags: list[str]¶

List of compiler flags to pass to Clang.

verbose: bool = False¶

Parse in verbose mode.

include_directory_map: dict[str, str]¶

Maps actual include directories to a displayed directory name.

The keys should be prefixes of paths specified in error messages/source locations identified by clang.

The values should be the corresponding prefix to use in the documented #include paths.

allow_paths: list[Pattern]¶

List of regular expressions matching allowed paths.

Only entities defined in files that match allow_paths, and don’t match disallow_paths, are documented. By default all entities are documented, but this default is not normally usable, because it will include entities defined in the standard library and third-party libraries.

Important

When building on Windows, all path separators are normalized to "/". Therefore, in the specified regular expressions, always use "/" to match a path separator.

disallow_paths: list[Pattern]¶

List of regular expressions matching disallowed paths.

Entities defined in files matching any of these patterns are not documented.

Important

When building on Windows, all path separators are normalized to "/". Therefore, in the specified regular expressions, always use "/" to match a path separator.

disallow_namespaces: list[Pattern]¶

List of regular expressions matching disallowed namespaces.

Entities defined in namespaces matching any of the specified patterns are not documented.

allow_symbols: list[Pattern]¶

List of regular expressions matching allowed symbols.

Only symbols matching one of the allow_symbols patterns, and not matching disallow_symbols, are documented. By default, all symbols are allowed.

disallow_symbols: list[Pattern]¶

List of regular expressions matching disallowed symbols.

Symbols matching any of these patterns are undocumented.

allow_macros: list[Pattern]¶

List of regular expressions matching allowed macros.

Only macros names matching allow_macros, and not matching disallow_macros, are documented.

disallow_macros: list[Pattern]¶

List of regular expressions matching disallowed macro names.

Macros matching any of these patterns are undocumented.

ignore_diagnostics: list[Pattern]¶

List of regular expressions matching diagnostics to ignore.

Diagnostics matching any of these patterns are ignored.

type_replacements: dict[str, str]¶

Remaps type names.

hide_types: list[Pattern]¶

List of regular expressions matching hidden types.

Matching return types are replaced with auto, and matching initializers are elided.

ignore_template_parameters: list[Pattern]¶

List of regular expressions matching ignored template parameters.

Template parameters with a declaration matching any of these patterns are excluded from the generated documentation.

hide_initializers: list[Pattern]¶

List of regular expressions matching initializers to elide.

Any matching initializer expression is elided from the generated documentation.

cpp_apigen_case_insensitive_filesystem : None | bool = None¶

This extension results in an output file for each documented C++ entity based on its fully-qualified name. C++ names are case-sensitive, meaning both foo and Foo can be defined within the same scope, but some filesystems are case insensitive (e.g. on Windows and macOS), which creates the potential for a conflict.

By default (if cpp_apigen_case_insensitive_filesystem is None), this extension detects automatically if the filesystem is case-insensitive, but detection is skipped if the option is set to an explicit value of True or False:

Add to conf.py to force case-insensitive naming scheme¶

cpp_apigen_case_insensitive_filesystem = True

If the filesystem is either detected or specified to be case-insensitive, case conflicts are avoided by including a hash in the document name.

cpp_apigen_rst_prolog : str = ''¶

A string of reStructuredText that will be included at the beginning of the documentation text for each entity.

This may be used to set the rST directive default-role, highlight language, or default-literal-role.

Note

The prior default role, default literal role, and default highlight langauge are automatically restored after processing the cpp_apigen_rst_epilog. Therefore, it is not necessary to manually add anything to cpp_apigen_rst_epilog to restore the prior roles or highlight language.

Setting default roles and highlight language in conf.py¶

rst_prolog = """
.. role cpp(code)
   :language: cpp
   :class: highlight
"""

cpp_apigen_rst_prolog = """
.. default-role:: cpp:expr

.. default-literal-role:: cpp

.. highlight:: cpp
"""

cpp_apigen_rst_epilog : str = ''¶

A string of reStructuredText that will be included at the end of the documentation text for each entity.

This option is supported for symmetry with cpp_apigen_rst_prolog, but in most cases is not needed because any changes to the default role, default literal role, and default highlight language due to cpp_apigen_rst_prolog are undone automatically.