Martin Thoma A blog about Code, Politics, and my life

Python Code Documentation

· by

Contents

Documenting 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

from typing import List


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

    :param algorithms: Preprocessing algorithms which get applied in order.
    :type algorithms: a list of 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)
    """
    for algorithm in algorithms:
        algorithm(self)

The Google Way

Google documented its format at google.github.io.

from typing import List


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

    Args:
      algorithms (a list of objects): Preprocessing algorithms 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)
    """
    for algorithm in algorithms:
        algorithm(self)

To make the Google way render well in Sphinx, you need Napoleon.

The NumPyDoc Way

from typing import List


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

    Parameters
    ----------
    algorithms : a list of objects
        Preprocessing algorithms 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)
    """
    for algorithm in algorithms:
        algorithm(self)

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

See also