usage.rst

Usage

This extension shows the default values in autodoc-formatted docstrings.

The default behaviour of autodoc is to turn this:

def namedlist(name: str = "NamedList") -> Callable:
    """
    A factory function to return a custom list subclass with a name.

    :param name: The name of the list.
    :default name: :py:obj:`True`

    :return:
    """

into this:

With default_values enabled, the documentation will now look like this:

Default values are taken from the function/class signature. They can be overridden using the :default <argname>: <default value> option in the docstring:

:param name: The name of the list.
:default name: :py:obj:`True`

which will produce:

The value must be formatted how you would like it to be displayed in Sphinx. This can be useful when the default value in the signature is :pyNone and the true default value is assigned in the function body, such as for a mutable default argument.

The default value can be suppressed using the :no-default <argname> option:

:param name: The name of the list.
:no-default name:

This allows for default values to be suppressed on a per-argument basis.

No default value is shown if the argument does not have a default value.

The formatting of the default value can be customised using the default_description_format option in setup.py. By default this is 'Default %s'.