Sphinx extension module to provide additional sections for numpy docstrings

This extension extends the sphinx.ext.napoleon package with an additional Possible types section in order to document possible types for descriptors.

Notes

If you use this module as a sphinx extension, you should not list the sphinx.ext.napoleon module in the extensions variable of your conf.py. This module has been tested for sphinx 1.3.1.

Classes:

DocstringExtension()	Class that introduces a "Possible Types" section
ExtendedGoogleDocstring(docstring[, config, ...])	sphinx.ext.napoleon.GoogleDocstring with more sections
ExtendedNumpyDocstring(docstring[, config, ...])	sphinx.ext.napoleon.NumpyDocstring with more sections

Functions:

process_docstring(app, what, name, obj, ...)	Process the docstring for a given python object.
setup(app)	Sphinx extension setup function

class psyplot.sphinxext.extended_napoleon.DocstringExtension

Bases: object

Class that introduces a “Possible Types” section

This class serves as a base class for sphinx.ext.napoleon.NumpyDocstring and sphinx.ext.napoleon.GoogleDocstring to introduce another section names Possible types

Examples

The usage is the same as for the NumpyDocstring class, but it supports the Possible types section:

>>> from sphinx.ext.napoleon import Config

>>> from psyplot.sphinxext.extended_napoleon import (
...     ExtendedNumpyDocstring,
... )
>>> config = Config(napoleon_use_param=True, napoleon_use_rtype=True)
>>> docstring = '''
... Possible types
... --------------
... type1
...     Description of `type1`
... type2
...     Description of `type2`'''
>>> print(ExtendedNumpyDocstring(docstring, config))
.. rubric:: Possible types

* *type1* --
  Description of `type1`
* *type2* --
  Description of `type2`

class psyplot.sphinxext.extended_napoleon.ExtendedGoogleDocstring(docstring: str | list[str], config: SphinxConfig | None = None, app: Sphinx | None = None, what: str = '', name: str = '', obj: Any = None, options: Any = None)

Bases: GoogleDocstring, DocstringExtension

sphinx.ext.napoleon.GoogleDocstring with more sections

class psyplot.sphinxext.extended_napoleon.ExtendedNumpyDocstring(docstring: str | list[str], config: SphinxConfig | None = None, app: Sphinx | None = None, what: str = '', name: str = '', obj: Any = None, options: Any = None)

Bases: NumpyDocstring, DocstringExtension

sphinx.ext.napoleon.NumpyDocstring with more sections

psyplot.sphinxext.extended_napoleon.process_docstring(app, what, name, obj, options, lines)

Process the docstring for a given python object.

Called when autodoc has read and processed a docstring. lines is a list of docstring lines that _process_docstring modifies in place to change what Sphinx outputs.

The following settings in conf.py control what styles of docstrings will be parsed:

• napoleon_google_docstring – parse Google style docstrings

• napoleon_numpy_docstring – parse NumPy style docstrings

Parameters:

• app (sphinx.application.Sphinx) – Application object representing the Sphinx process.

• what (str) – A string specifying the type of the object to which the docstring belongs. Valid values: “module”, “class”, “exception”, “function”, “method”, “attribute”.

• name (str) – The fully qualified name of the object.

• obj (module, class, exception, function, method, or attribute) – The object to which the docstring belongs.

• options (sphinx.ext.autodoc.Options) – The options given to the directive: an object with attributes inherited_members, undoc_members, show_inheritance and noindex that are True if the flag option of same name was given to the auto directive.

• lines (list of str) –

  The lines of the docstring, see above.

  Note

  lines is modified in place

Notes

This function is (to most parts) taken from the sphinx.ext.napoleon module, sphinx version 1.3.1, and adapted to the classes defined here

psyplot.sphinxext.extended_napoleon.setup(app)

Sphinx extension setup function

When the extension is loaded, Sphinx imports this module and executes the setup() function, which in turn notifies Sphinx of everything the extension offers.

Parameters:

app (sphinx.application.Sphinx) – Application object representing the Sphinx process

Notes

This function uses the setup function of the sphinx.ext.napoleon module