• Martin Thoma
  • Home
  • Categories
  • Tags
  • Archives
  • Support me

Python Code Documentation

Contents

  • The Sphinx Way
  • The Google Way
  • The NumPyDoc Way
  • See also

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

from typing import List


def preprocessing(self, algorithms: List):
    """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)
    """
    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 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)
    """
    for algorithm in algorithms:
        algorithm(self)

To get 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 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)
    """
    for algorithm in algorithms:
        algorithm(self)

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

See also

  • A Guide to NumPy/SciPy Documentation
  • sphinxcontrib-napoleon.readthedocs.org: A longer numpydoc example

Published

Apr 8, 2015
by Martin Thoma

Category

Code

Tags

  • Documentation 2
  • Python 141

Contact

  • Martin Thoma - A blog about Code, the Web and Cyberculture
  • E-mail subscription
  • RSS-Feed
  • Privacy/Datenschutzerklärung
  • Impressum
  • Powered by Pelican. Theme: Elegant by Talha Mansoor