Formatting signatures

This theme supports three alternative ways to automatically format/indent API documentation signatures.

Basic function parameter wrapping

As of Sphinx 7.1, the maximum_signature_line_length option (and its domain-specific variants) may be used to enable basic automatic parameter wrapping. The recommended limit for this theme is 68.

Warning

Even with the recommended limit of 68, signature lines may be too long and display poorly on very narrow browser viewports, such as mobile phones in portrait mode.

This theme also supports a CSS-based formatting rule that can be enabled for long function signatures that displays each function parameter on a separate line. This is enabled by default (when the maximum_signature_line_length option is not enabled), and works fairly well for Python signatures.

It is controlled by the following object description options:

wrap_signatures_with_css : bool = True

Indicates whether CSS-based formatting is enabled. Disabled automatically if clang_format_style or black_format_style is specified. Also disabled automatically if the global or domain-specific maximum_signature_line_length option is enabled.

wrap_signatures_column_limit : int = 68

Maximum signature length before function parameters are displayed on separate lines.

Only applies if wrap_signatures_with_css is set to True, or if clang_format_style is enabled and does not specify a ColumnLimit value.

The default value is 68. This is the number of characters that fit under typical display settings with both left and right side bars displayed.

For example, to disable this option for every domain except py, add the following to conf.py:

object_description_options = [
    (".*", dict(wrap_signatures_with_css=False)),
    ("py:.*", dict(wrap_signatures_with_css=True)),
]
CSS-based wrapping of Python signature
.. py:function:: long_function_signature_example(\
                   name: int, \
                   other_param: list[str], \
                   yet_another: bool = False, \
                   finally_another: str = "some long string goes here"\
                 ) -> Tuple[str, bool, float, bytes, int]
long_function_signature_example(
    name: int,
    other_param: list[str],
    yet_another: bool = False,
    finally_another: str = "some long string goes here",) -> tuple[str, bool, float, bytes, int]

Note

The maximum_signature_line_length and wrap_signatures_with_css options produce similar results.

The key differences are:

With either option, individual parameters that are too long to fit on a single line will not be wrapped/indented properly. For more advanced formatting, the External code formatter integration is recommended instead.

External code formatter integration

There is a more powerful alternative formatting mechanism that makes use of external code formatters.

Warning

The LaTeX builder is supported. However, the spacing may not always line up correctly because the Latex builder does not use a monospace font for the entire signature.

clang-format

The clang-format integration supports C, C++, Java, JavaScript, Objective-C, and C#.

This functionality is available as a separate extension included with this theme. To use it, you must include it in your conf.py file and you must also specify the clang_format_style option for the object types for which the extension should be used.

extensions = [
    # other extensions...
    "sphinx_immaterial.apidoc.format_signatures",
]

object_description_options = [
    # ...
    ("cpp:.*", dict(clang_format_style={"BasedOnStyle": "LLVM"})),
]
clang_format_style : str | dict[str, Any] | None = None

Specifies the clang-format style options as a dict (JSON object), or None to disable clang-format.

If the style does not explicitly specify a ColumnLimit, the value of wrap_signatures_column_limit is used.

Warning

Due to how this extension is implemented, style options that change non-whitespace characters, such as setting QualifierAlignment to a value other than Leave, must not be used (if non-whitespace characters are changed, the extension will raise an exception and the documentation build will fail).

clang_format_command : str = 'clang-format'

Name of clang-format executable. May either be a plain filename, in which case normal PATH resolution applies, or a path to the executable. Defaults to "clang-format".

To ensure that a consistent version of clang-format is available when building your documentation, add the clang-format PyPI package as a dependency, or depend on the clang-format optional feature of this package:

pip install sphinx-immaterial[clang-format]

.. cpp:function:: template <typename T, \
                            typename U = void, \
                            int AnotherParameter = 42> \
                  requires std::is_const_v<T> \
                  const MyType LongFunctionSignatureExample(\
                    const MyType bar, \
                    uint8_t* arr, \
                    unsigned int len = DEFAULT_LENGTH, \
                    bool baz = false);

   Some function type thing
template <typename T, typename U = void, int AnotherParameter = 42>
  requires std::is_const_v<T>
const MyType
LongFunctionSignatureExample(const MyType bar, uint8_t *arr,
                             unsigned int len = DEFAULT_LENGTH,
                             bool baz = false);

Some function type thing

black

The Black integration supports Python.

This functionality is available as a separate extension included with this theme. To use it, you must include it in your conf.py file and you must also specify the black_format_style option for the object types for which the extension should be used.

extensions = [
    # other extensions...
    "sphinx_immaterial.apidoc.format_signatures",
]

object_description_options = [
    # ...
    ("py:.*", dict(black_format_style={"line_length": 60})),
]
black_format_style : sphinx_immaterial.apidoc.format_signatures.BlackFormatStyle | None = None

Specifies style options for black, or None to disable black.

If the style does not explicitly specify a line_length, the value of wrap_signatures_column_limit is used.

class sphinx_immaterial.apidoc.format_signatures.BlackFormatStyle[source]
line_length: int | None = None

Line length limit.

Defaults to the value of wrap_signatures_column_limit.

string_normalization: bool = True

Indicates whether to normalize quotes. This corresponds to the inverse of Black CLI’s –skip-string-normalization option.

.. py:function:: some_module.method_name( \
                   some_parameter_with_a_long_name: \
                     collections.abc.MutableMapping[\
                       tuple[str, float, numbers.Real], \
                       dict[int, tuple[list[frozenset[int]]]]], \
                 ) -> collections.abc.MutableMapping[\
                        tuple[str, float, numbers.Real], \
                        dict[int, tuple[list[frozenset[int]]]]]
   :noindex:

   Some function doc.
some_module.method_name(
    some_parameter_with_a_long_name: collections.abc.MutableMapping[
        tuple[str, float, numbers.Real],
        dict[int, tuple[list[frozenset[int]]]],
    ],
) -> collections.abc.MutableMapping[
    tuple[str, float, numbers.Real],
    dict[int, tuple[list[frozenset[int]]]],
]

Some function doc.