Skip to main content

Sphinx "napoleon" extension.

Project description

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:

    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

    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.

Getting Started

  1. Install the napoleon extension:

    $ pip install sphinxcontrib-napoleon
  2. After setting up Sphinx to build your docs, enable napoleon in the Sphinx file:

    # Add napoleon to the extensions list
    extensions = ['sphinxcontrib.napoleon']
  1. Use sphinx-apidoc to build your API documentation:

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


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.

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.

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

        bool: Description of return value

    return True

NumPy style:

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

    Extended description of function.

    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

        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

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinxcontrib-napoleon-0.7.tar.gz (21.2 kB view hashes)

Uploaded source

Built Distribution

sphinxcontrib_napoleon-0.7-py2.py3-none-any.whl (17.2 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page