pydoctor.napoleon

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:

• Google-style
• NumpyDoc-style

:

    @copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
    @license: BSD, see LICENSE for details.