This release is a pre-release and may not be stable for production use.
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 mess 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 allows you to write readable API documentation in your source code. Napoleon understands both Google and NumPy style docstrings.
Getting Started
After setting up Sphinx to build your project docs, install the sphinxcontrib-napoleon package:
$ pip install sphinxcontrib-napoleon
Enable napoleon in the Sphinx conf.py file:
# conf.py # Add autodoc and napoleon to the extensions list extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.napoleon']
Docstrings
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
Args:
arg1 (int): Description of arg1
arg2 (str): Description of arg2
Returns:
bool: Description of return value
# NumPy Style
Parameters
----------
arg1 : int
Description of arg1
arg2 : str
Description of arg2
Returns
-------
bool
Description of return value
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 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.
Development Setup
Prerequisites
Python - sudo brew install python
Paver - sudo pip install paver
Dev Environment
$ paver bootstrap $ source virtualenv/bin/activate $ python setup.py develop
1 maintainer
Metadata
1 maintainer
Release files for sphinxcontrib-napoleon 0.1dev-20130718
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.1dev-20130718.tar.gz | 18.0 kB | Details |
Release files / sphinxcontrib-napoleon-0.1dev-20130718.tar.gz
| Download URL | sphinxcontrib-napoleon-0.1dev-20130718.tar.gz |
|---|---|
| Size | 18.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0cf7e9d7af6af588ad02d155cbab1d2665b057843aece1aab00ba473d7c6ad71
|
|
BLAKE2b-256 checksum How to use checksums |
226373571034d56b8542a1fe170414877af4c657396997305b5027c1ee258125
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
