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.

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

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.

Docstring Sections All of the following section headers are supported: Args (alias of Parameters)

(alias of Parameters) Arguments (alias of Parameters)

(alias of Parameters) Attributes

Example

Examples

Keyword Args (alias of Keyword Arguments)

(alias of Keyword Arguments) Keyword Arguments

Methods

Note

Notes

Other Parameters

Parameters

Return (alias of Returns)

(alias of Returns) Returns

Raises

References

See Also

Warning

Warnings (alias of Warning)

(alias of Warning) Warns

Yield (alias of Yields)

(alias of Yields) Yields