Napoleon - Marching toward legible docstrings
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)
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.
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
1 maintainer
Metadata
1 maintainer
Release files for sphinxcontrib-napoleon 0.7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| sphinxcontrib-napoleon-0.7.tar.gz | 21.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| sphinxcontrib_napoleon-0.7-py2.py3-none-any.whl | Python 3, Python 2 | none | any | Details |
Total release size: 38.4 kB
Release files / sphinxcontrib-napoleon-0.7.tar.gz
| Download URL | sphinxcontrib-napoleon-0.7.tar.gz |
|---|---|
| Size | 21.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
407382beed396e9f2d7f3043fad6afda95719204a1e1a231ac865f40abcbfcf8
|
|
BLAKE2b-256 checksum How to use checksums |
faebad89500f4cee83187596e07f43ad561f293e8e6e96996005c3319653b89f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/1.11.0 pkginfo/1.4.2 requests/2.18.4 setuptools/28.8.0 requests-toolbelt/0.8.0 tqdm/4.19.5 CPython/3.6.3
|
Release files / sphinxcontrib_napoleon-0.7-py2.py3-none-any.whl
| Download URL | sphinxcontrib_napoleon-0.7-py2.py3-none-any.whl |
|---|---|
| Size | 17.2 kB |
| Tags | Python 2 Python 3 |
|
SHA-256 checksum How to use checksums |
711e41a3974bdf110a484aec4c1a556799eb0b3f3b897521a018ad7e2db13fef
|
|
BLAKE2b-256 checksum How to use checksums |
75f26b7627dfe7b4e418e295e254bb15c3a6455f11f8c0ad0d43113f678049c3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/1.11.0 pkginfo/1.4.2 requests/2.18.4 setuptools/28.8.0 requests-toolbelt/0.8.0 tqdm/4.19.5 CPython/3.6.3
|
