Napoleon -Marching toward legible docstrings

Note

As of Sphinx 1.3, the napoleon extension will come packaged withSphinx undersphinx.ext.napoleon. Thesphinxcontrib.napoleon extensionwill 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 readdocstrings. Compare the jumble above to the same thing rewrittenaccording to theGoogle 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 destructedReturns:    BufferedFileStorage: A buffered writable file descriptor

Much more legible, no?

Napoleon is aSphinx extension that enables Sphinx to parse bothNumPyandGoogle style docstrings - the style recommended byKhan Academy.

Napoleon is a pre-processor that parsesNumPy andGoogle styledocstrings and converts them to reStructuredText before Sphinx attempts toparse them. This happens in an intermediate step while Sphinx is processingthe documentation, so it doesn’t modify any of the docstrings in your actualsource code files.

Getting Started

  1. Install the napoleon extension:

    $ pip install sphinxcontrib-napoleon

  2. Aftersetting up Sphinx to build your docs, enable napoleon in theSphinxconf.py file:

    # conf.py# Add napoleon to the extensions listextensions=['sphinxcontrib.napoleon']

  3. Usesphinx-apidoc to build your API documentation:

    $ sphinx-apidoc -f -o docs/source projectdir

Docstrings

Napoleon interprets every docstring thatSphinx autodoc can find,including docstrings on:modules,classes,attributes,methods,functions, andvariables. Inside each docstring,specially formattedSections are parsed and converted toreStructuredText.

All standard reStructuredText formatting still works as expected.

Docstring Sections

All of the following section headers are supported:

  • Args(alias of Parameters)
  • Arguments(alias of Parameters)
  • Attributes
  • Example
  • Examples
  • KeywordArgs(alias of Keyword Arguments)
  • KeywordArguments
  • Methods
  • Note
  • Notes
  • OtherParameters
  • Parameters
  • Return(alias of Returns)
  • Returns
  • Raises
  • References
  • SeeAlso
  • Todo
  • Warning
  • Warnings(alias of Warning)
  • Warns
  • Yield(alias of Yields)
  • Yields

Google vs NumPy

Napoleon supports two styles of docstrings:Google andNumPy. Themain difference between the two styles is that Google uses indention toseparate sections, whereas NumPy uses underlines.

Google style:

deffunc(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    """returnTrue

NumPy style:

deffunc(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    """returnTrue

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

TheKhan Academy recommends using Google style.

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

Type Annotations

PEP 484 introduced a standard way to express types in Python code.This is an alternative to expressing types directly in docstrings.One benefit of expressing types according toPEP 484 is thattype checkers and IDEs can take advantage of them for static codeanalysis.

Google style with Python 3 type annotations:

deffunc(arg1:int,arg2:str)->bool:"""Summary line.    Extended description of function.    Args:        arg1: Description of arg1        arg2: Description of arg2    Returns:        Description of return value    """returnTrue

Google style with types in docstrings:

deffunc(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    """returnTrue

Note

Python 2/3 compatible annotations aren’t currentlysupported by Sphinx and won’t show up in the docs.

Configuration

For detailed configuration options seesphinxcontrib.napoleon.Config.