Napoleon - Marching toward legible docstrings

.. note:: As of Sphinx 1.3, the napoleon extension will come packaged with
Sphinx under sphinx.ext.napoleon. The sphinxcontrib.napoleon extension
will continue to work with Sphinx <= 1.2.

Are you tired of writing docstrings that look like this::

:param path: The path of the file to wrap
:type path: str
:param field_storage: The :class:`FileStorage` instance to wrap
:type field_storage: FileStorage
:param temporary: Whether or not to delete the file when the File
   instance is destructed
:type temporary: bool
:returns: A buffered writable file descriptor
:rtype: BufferedFileStorage

ReStructuredText_ is great, but it creates visually dense, hard to read
docstrings. Compare the jumble above to the same thing rewritten
according to the Google Python Style Guide::

Args:
    path (str): The path of the file to wrap
    field_storage (FileStorage): The :class:`FileStorage` instance to wrap
    temporary (bool): Whether or not to delete the file when the File
       instance is destructed

Returns:
    BufferedFileStorage: A buffered writable file descriptor

Much more legible, no?

Napoleon is a Sphinx extension_ that enables Sphinx to parse both NumPy_
and Google_ style docstrings - the style recommended by Khan Academy_.

Napoleon is a pre-processor that parses NumPy_ and Google_ style
docstrings and converts them to reStructuredText before Sphinx attempts to
parse them. This happens in an intermediate step while Sphinx is processing
the documentation, so it doesn't modify any of the docstrings in your actual
source code files.

.. _ReStructuredText: http://docutils.sourceforge.net/rst.html
.. _docstrings: http://www.python.org/dev/peps/pep-0287/
.. _Google Python Style Guide:
http://google.github.io/styleguide/pyguide.html
.. _Sphinx extension: http://sphinx-doc.org/extensions.html
.. _Google:
http://google.github.io/styleguide/pyguide.html#Comments
.. _NumPy:
https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
.. _Khan Academy:
https://sites.google.com/a/khanacademy.org/forge/for-developers/styleguide/python#TOC-Docstrings

Getting Started

Install the napoleon extension::
```
$ pip install sphinxcontrib-napoleon
```

After setting up Sphinx_ to build your docs, enable napoleon in the
Sphinx conf.py file::

# conf.py

# Add napoleon to the extensions list
extensions = ['sphinxcontrib.napoleon']

Use sphinx-apidoc to build your API documentation::
```
$ sphinx-apidoc -f -o docs/source projectdir
```

.. _setting up Sphinx: http://sphinx-doc.org/tutorial.html

Docstrings

Napoleon interprets every docstring that Sphinx autodoc_ can find,
including docstrings on: modules, classes, attributes,
methods, functions, and variables. Inside each docstring,
specially formatted Sections_ are parsed and converted to
reStructuredText.

All standard reStructuredText formatting still works as expected.

.. _Sphinx autodoc: http://sphinx-doc.org/ext/autodoc.html

.. _Sections:

Docstring Sections

All of the following section headers are supported:

* ``Args`` *(alias of Parameters)*
* ``Arguments`` *(alias of Parameters)*
* ``Attributes``
* ``Example``
* ``Examples``
* ``Keyword Args`` *(alias of Keyword Arguments)*
* ``Keyword Arguments``
* ``Methods``
* ``Note``
* ``Notes``
* ``Other Parameters``
* ``Parameters``
* ``Return`` *(alias of Returns)*
* ``Returns``
* ``Raises``
* ``References``
* ``See Also``
* ``Warning``
* ``Warnings`` *(alias of Warning)*
* ``Warns``
* ``Yield`` *(alias of Yields)*
* ``Yields``

Google vs NumPy

Napoleon supports two styles of docstrings: Google_ and NumPy_. The
main difference between the two styles is that Google uses indention to
separate sections, whereas NumPy uses underlines.

Google style::

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Args:
        arg1 (int): Description of arg1
        arg2 (str): Description of arg2

    Returns:
        bool: Description of return value

    """
    return True

NumPy style::

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    """
    return True

NumPy style tends to require more vertical space, whereas Google style
tends to use more horizontal space. Google style tends to be easier to
read for short and simple docstrings, whereas NumPy style tends be easier
to read for long and in-depth docstrings.

The Khan Academy_ recommends using Google style.

The choice between styles is largely aesthetic, but the two styles should
not be mixed. Choose one style for your project and be consistent with it.

For full documentation see https://sphinxcontrib-napoleon.readthedocs.io

Dependencies of sphinxcontrib-napoleon (2).
Dependency	Optional
pockets	false
six	false

Package profile

sphinxcontrib-napoleon

Releases

Release table

PyPI Downloads

Dependencies

Details

Project URLs

Dependencies

Package description