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