General API customization

This theme supports a number of options that can be customized for each domain/object type pair.

object_description_options : list[tuple[Pattern, dict[str, Any]]] = []

list of (pattern, options) pairs, where pattern is a regular expression matching strings of the form "domain:objtype" and options is a dictionary of supported Object description options.

The actual options for a given object type are determined by first initializing each option to its default value, and then applying as overrides the options associated with each matching pattern in order.

Object description options

The following options can be customized for each object type using object_description_options.

include_in_toc : bool = True

Indicates whether to include the object description in the table of contents.

Example

To prevent C++ parameter descriptions from appearing in the TOC, add the following to conf.py:

object_description_options = [
    ("cpp:.*Param", dict(include_in_toc=False)),
]
generate_synopses : 'first_paragraph' | 'first_sentence' | None = 'first_paragraph'

Indicates whether to generate a synopsis from the object description. The synopsis is shown as a tooltip when hovering over a cross-reference link, and is also shown in the search results list. Supported values are:

None

Disables synopsis generation.

"first_paragraph"

Uses the first paragraph of the description as the synopsis.

"first_sentence"

Uses the first sentence of the first paragraph of the description as the synopsis.

The default is "first_paragraph" except for c(pp)?:.*Param where the default is "first_sentence".

Note

Synopsis generation is currently supported only for the following domains:

Example

To use the first sentence rather than the first paragraph as the synopsis for C++ class descriptions, add the following to conf.py:

object_description_options = [
    ("cpp:class", dict(generate_synopses="first_sentence")),
]
include_object_type_in_xref_tooltip : bool = True

Indicates whether to include the object type in cross-reference and TOC tooltips.

Note

For TOC entries, this is supported for all domains. For regular cross references, this is supported only for the following domains:

Example

To exclude the object type from all py domain xrefs, add the following to conf.py:

object_description_options = [
    ("py:.*", dict(include_object_type_in_xref_tooltip=False)),
]
include_fields_in_toc : bool = True

Indicates whether to include fields, like “Parameters”, “Returns”, “Raises”, etc., in the table of contents.

For an example, see: synopses_ex::Foo and note the Template Parameters, Parameters, and Returns headings shown in the right-side table of contents.

Note

To control whether there are separate TOC entries for individual parameters, such as for synopses_ex::Foo::T, synopses_ex::Foo::N, synopses_ex::Foo::param, and synopses_ex::Foo::arr, use the include_in_toc option.

Example

To exclude object description fields from the table of contents for all py domain objects, add the following to conf.py:

object_description_options = [
    ("py:.*", dict(include_fields_in_toc=False)),
]
include_rubrics_in_toc : bool = False

Indicates whether to include rubrics in object descriptions, like “Notes”, “References”, “Examples”, etc., in the table of contents.

Note

Traditionally, rubrics are not intended to be included in the table of contents. However with include_fields_in_toc, rubric-like fields may be included in the TOC. Including other rubrics from the object description in the TOC is provided for visual consistency.

Example

To include object description rubrics in the table of contents for all py domain objects, add the following to conf.py:

object_description_options = [
    ("py:.*", dict(include_rubrics_in_toc=True)),
]

Other options described elsewhere include:

Table of contents icons

For object descriptions included in the table of contents (when include_in_toc is True), a text-based “icon” can optionally be included to indicate the object type.

Default icons are specified for a number of object types, but they can be overridden using the following options:

toc_icon_class : str | None = None

Indicates the icon class, or None to disable the icon. The class must be one of:

  • "alias"

  • "procedure"

  • "data"

  • "sub-data"

toc_icon_text : str | None = None

Indicates the text content of the icon, or None to disable the icon. This should normally be a single character, such as "C" to indicate a class or "F" to indicate a function.

Example

To define a custom object type and specify an icon for it, add the following to conf.py:

object_description_options = [
    ("std:confval", dict(toc_icon_class="data", toc_icon_text="C")),
]

def setup(app):
    app.add_object_type(
        "confval",
        "confval",
        objname="configuration value",
        indextemplate="pair: %s; configuration value",
    )
Last update: Dec 16, 2024