Documentation

Documentation helps people (or your future self) understand how to use your software.

Benefits of documentation include higher likelihood of the software being adopted and supported by others.

Specific ways of implementing documentation in Python are with docstrings and type hints.

When Python code is documented according to certain conventions, it is possible to auto-generate entire documentation reference websites, using auto-documentation tools.

Docstrings

Docstrings allow Python developers to document their code in a way which can be interpreted by other computers and humans alike.

“The docstring for a function or method should summarize its behavior and document its arguments, return value(s), side effects, exceptions raised, and restrictions on when it can be called (all if applicable). Optional arguments should be indicated. It should be documented whether keyword arguments are part of the interface.” - PEP 257

Example function, before documentation:

def enlarge(n):
    return n * 100

Example function, complete with docstring:

def enlarge(n):
    """
    Enlarges a number.

    Params:

        n : (numeric, like int or float) the number to be enlarged

    Examples:

        enlarge(8)

        enlarge(4.5)
    """
    return n * 100

The multiline string can look intimidating, but docstrings have practical benefits. Python tools and text editors will recognize the docstring and show a helper message to anyone who is trying to use / invoke that function:

Example of how a docstring is displayed by development tools, to provide context about that function

You don’t need to follow any specific conventions with your docstrings for them to be valid. However if you are looking for some specific recommendations for how to structure your docstrings, consider adopting one of the following conventions:

Auto-Documentation

Tools like Sphinx, MkDocs, Jupyter Book, and Quarto can generate auto-generate entire documentation sites based on docstring content, especially if the docstrings conform to certain conventions. Read The Docs is a popular hosting provider for Python package documentation sites.

To create your own auto-documentation site for a Python package, feel free to leverage this Quarto Python Package Autodoc Template repository.

Example Auto-Documentation Site: Pandas Package

Observe the documentation site for the DataFrame class, and corresponding source code. Notice the phrase “Two-dimensional, size-mutable, potentially heterogeneous tabular data”, as well as the function parameters, are coming from the docstring.

Example Auto-Documentation Site: Truthbrush

Observe the documentation site for the Api class, and corresponding source code. Observe these examples of Google-style docstring formatting.

class Api:
    """A client for interfacing with the API.

    Params:
        username (str): The user name for logging in to the API.
        password (str): The password for logging in to the API.

    Examples:
        Initialize the client by passing your username and password:
        ```python
        from my_package import Api
        client = Api(username="yourname", password="yourpass")
        ```
    """

Type Hints

Another way of documenting functions more formally is a type hint.

Type hints allow us to specify:

  1. Which datatypes are expected for each parameter, by using a colon (:) to the right of each parameter name
  2. Which datatype will be returned by the function, by using a right arrow (->) to the right of the function definition
# FUNCTION DEFINITION:

def enlarge(n:float) -> float: # OBSERVE THE TYPE HINTS
    return n * 100.0

# FUNCTION INVOCATIONS:

print(enlarge(9))

print(enlarge(3))

x = 10
print(enlarge(x))
900.0
300.0
1000.0

In this example we are using a basic datatype (float) in the type hints, but for more advanced type hints, we can consider using the typing module. For more information, consult the type hints cheat sheet.

Ultimately these type hints are just suggestions, and they won’t perform validations or prevent different datatypes from being passed in.