Skip to main content

Sphinx "napoleon" extension.

Project description

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for sphinxcontrib-napoleon, version 0.1dev-20130718
Filename, size File type Python version Upload date Hashes
Filename, size sphinxcontrib-napoleon-0.1dev-20130718.tar.gz (18.0 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page