Convert docstrings from numpy or google style format to reST.
This package is a fork of sphinx.ext.napoleon
adapted for pydoctor usage.
The following list roughtly describes the changes:
Use more type parsing:
All types will be pre-processed and links will be automtically created when possible. See
TypeDocstring
for examples of what's a valid type specification string.Types in google-style Returns and Args clauses can span multiple lines:
This will be understood correctly:
Args: docstring (Union[ list[str] str, list[twisted.python.compat.NativeStringIO], twisted.python.compat.NativeStringIO]): The docstring. Note that this last indentation is optional. errors (Sequence[Union[ParseError, ParseWarning, ParseInfo, ...]]): The list of errors, warnings or other informations.
More flexible numpy-style Returns clause:
Allow users who have type annotations in their pure python code to omit types in the returns clause docstrings but as well as specify them when it's needed. Just as google-style docstring (but without the multiline type support)
All of the following return clauses will be interpreted as expected:
Returns ------- Description of return value Returns ------- subprocess.Popen Description of return value Returns ------- list[str] Returns ------- list of str
See: sphinx/issues/7077
No settings are supported for a more straight-forward usage simple usage. Also there is no support for custom sections or type aliases.
Docformat references:
:
@copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. @license: BSD, see LICENSE for details.
Note | |
Sphinx Napoleon related PRs and issues should be checked once in a while to make sure we don't miss any important updates. |
Module | docstring |
Classes for google-style and numpy-style docstring conversion. |
Module | iterators |
A collection of helpful iterators. |