Function and class documentation best practices for Python

Answer 1

I think the best resource will be Documenting Python

Quote:

This document describes the style guide for our documentation, the custom reStructuredText markup introduced to support Python documentation and how it should be used, as well as the Sphinx build system.

Sphinx: The official Python documentation generator

Answer 2

The best way to learn documentation practices is probably to look at the source code of a well known project. Like the Djangoproject.

Answer 3

You should use reStructuredText and check out the Sphinx markup constructs. All the cool kids are doing it.

You should follow docstring conventions. i.e.

It prescribes the function or method's effect as a command ("Do this", "Return that").

You should avoid repeating yourself unnecessarily or explaining the eminently obvious. Example of what not to do:

def do_things(verbose=False):
    """Do some things.
    :param verbose: Be verbose (give additional messages).
    """
    raise NotImplementedError

If you wanted to describe something non-obvious it would be a different story; for example, that verbose causes messages to occur on stdout or a logging stream. This is not specific to Python, but follows from more hand-wavy ideals such as self-documenting code and code/documentation DRY.

Try to avoid mentioning specific types if possible (abstract or interface-like types are generally okay). Mentioning protocols is typically more helpful from a duck typing perspective (i.e. "iterable" instead of set, or "mutable ordered sequence" instead of list). I've seen some code that is very literal and heavy WRT the :rtype: and the :type param: function-level documentation, which I've found to be at odds with the duck typing mentality.

Answer 4

As Emji said, Django is a good project to follow for clear, consistent style guides.

For example, their Contribute to Django style guide even goes as far as describing how they'd like to see documentation. Specifically they mention:

In docstrings, use “action words” such as:

def foo():
    """
    Calculates something and returns the result.
    """
    pass

Here's an example of what not to do:

def foo():
    """
    Calculate something and return the result.
    """
    pass