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:

_images/before.png

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

_images/after.png

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:

_images/override.png

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 None 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:
_images/before.png

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'.