Python Code Documentation

Documentating your code is important when you make non-trivial projects. The standard way to document Python code is with Sphinx. You write the documentation files with reStructuredText.

One of the most important Sphinx plugins is autodoc. This allows you to generate the documentation of modules, classes and functions automatically by using their docstrings.

There are 3 standard ways to write docstrings: Sphinxy, Googley or NumPyDocy.

The Sphinx Way

def preprocessing(self, algorithms):
    """Apply preprocessing algorithms.

    :param algorithms: Preprocessing allgorithms which get applied in order.
    :type algorithms: a list objects

    >>> import preprocessing
    >>> a = HandwrittenData(...)
    >>> preprocessing_queue = [(preprocessing.scale_and_shift, []),
    ...                        (preprocessing.connect_strokes, []),
    ...                        (preprocessing.douglas_peucker,
    ...                         {'EPSILON': 0.2}),
    ...                        (preprocessing.space_evenly,
    ...                         {'number': 100,
    ...                          'KIND': 'cubic'})]
    >>> a.preprocessing(preprocessing_queue)
    """
    assert type(algorithms) is list
    for algorithm in algorithms:
        algorithm(self)

The Google Way

Google documented its format at http://google-styleguide.googlecode.com/. (I'm wondering where that will move, now that they plan to shut code.google.com down. Probably to GitHub.)

def preprocessing(self, algorithms):
    """Apply preprocessing algorithms.

    Args:
      algorithms (a list objects): Preprocessing allgorithms which get
        applied in order.

    Examples:

      >>> import preprocessing
      >>> a = HandwrittenData(...)
      >>> preprocessing_queue = [(preprocessing.scale_and_shift, []),
      ...                        (preprocessing.connect_strokes, []),
      ...                        (preprocessing.douglas_peucker,
      ...                         {'EPSILON': 0.2}),
      ...                        (preprocessing.space_evenly,
      ...                         {'number': 100,
      ...                          'KIND': 'cubic'})]
      >>> a.preprocessing(preprocessing_queue)
    """
    assert type(algorithms) is list
    for algorithm in algorithms:
        algorithm(self)

To get the google way render well in Sphinx, you need Napoleon.

The NumPyDoc Way

def preprocessing(self, algorithms):
    """Apply preprocessing algorithms.

    Parameters
    ----------
    algorithms : a list objects
        Preprocessing allgorithms which get applied in order.

    Examples
    --------
    >>> import preprocessing
    >>> a = HandwrittenData(...)
    >>> preprocessing_queue = [(preprocessing.scale_and_shift, []),
    ...                        (preprocessing.connect_strokes, []),
    ...                        (preprocessing.douglas_peucker,
    ...                         {'EPSILON': 0.2}),
    ...                        (preprocessing.space_evenly,
    ...                         {'number': 100,
    ...                          'KIND': 'cubic'})]
    >>> a.preprocessing(preprocessing_queue)
    """
    assert type(algorithms) is list
    for algorithm in algorithms:
        algorithm(self)

To make numpydoc render well, you need the numpydoc sphinx extension.

See also

Published


by

Category

Code

Tags

Contact