package documentation

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:

            docstring (Union[
                list[str] str,
                twisted.python.compat.NativeStringIO]): The
                    docstring. Note that this last indentation is
            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:

        Description of return value
            Description of return value
        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.
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.