Sphinx "napoleon" extension.
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
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 allows you to write readable API documentation in your source code. Napoleon understands both NumPy and Google style docstrings - the style recommended by Khan Academy.
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)
- Keyword Args (alias of Keyword Arguments)
- Keyword Arguments
- Other Parameters
- Return (alias of Returns)
- See Also
- Warnings (alias of Warning)
Google vs NumPy
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
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 http://sphinxcontrib-napoleon.readthedocs.org