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.
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 autodoc and napoleon to the extensions list extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.napoleon']
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.
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
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