Common Docstring Formats in Python

Introduction

When you're knee-deep in Python code, comprehensive documentation can be a lifesaver (but, admittedly, the last thing you want to write). It's an important part of programming, and Python, being a highly readable and straightforward language, places great emphasis on it.

One key component of Python documentation is the docstring, a unique feature that sets Python apart from many other languages. In this article, we'll delve into what a docstring is and explore some of the most common docstring formats used in Python.

What is a Docstring?

A docstring, short for documentation string, is a literal string used right after the definition of a function, method, class, or module. It captures the essence of what the function does, providing an easy reference for the programmer. In Python, a docstring is a first-class citizen, meaning it can be accessed programmatically using the __doc__ attribute.

Here's a simple Python function with a docstring:

def add_numbers(a, b):
    """
    Adds two numbers together.

    Args:
        a (int): The first number.
        b (int): The second number.

    Returns:
        int: The sum of the two numbers.
    """
    return a + b

And here's how you can access the docstring:

print(add_numbers.__doc__)

The output will be:

Adds two numbers together.

Args:
    a (int): The first number.
    b (int): The second number.

Returns:
    int: The sum of the two numbers.

There's really no strict rule on how to write a docstring, although several widely accepted formats make the docstrings more structured and useful. These formats not only help in understanding the code, but they also allow tools like Sphinx, PyDoc, and Doxygen to automatically generate well-formatted documentation.

We'll look at these formats in the following sections.

Common Python Docstring Formats

Docstrings in Python are a powerful tool for documenting your code. They're essentially comments that are written in a specific format, which allows them to be parsed by documentation generation tools. There are several common formats for writing docstrings, and they each have their own strengths and weaknesses. The most commonly used formats are reStructuredText (reST), Google, NumPy/SciPy, and Epytext.

ReStructured Text (reST) Docstring Format

ReStructuredText, often abbreviated as reST, is a file format for textual data used primarily in the Python community for technical documentation. It's the default plaintext markup language used by Sphinx, a Python documentation generator.

In a reST docstring, you would typically start with a brief description of the function's purpose. You would then include sections for :param: to describe input parameters, :returns: to describe the return value, and :raises: to describe any exceptions that the function may raise.

Here's an example of what a reST docstring might look like:

def add_numbers(x, y):
    """
    Adds two numbers together.

    :param x: The first number to add
    :type x: int or float
    :param y: The second number to add
    :type y: int or float
    :returns: The sum of x and y
    :rtype: int or float
    :raises ValueError: If either x or y is not an int or float
    """
    if not isinstance(x, (int, float)) or not isinstance(y, (int, float)):
        raise ValueError('Both x and y must be ints or floats')
    return x + y

In this example, the docstring starts with a brief description of the function. It then uses :param: to describe the input parameters x and y, :type: to specify their types, :returns: to describe the return value, and :raises: to describe the ValueError exception that the function may raise.

Google Docstring Format

The Google Docstring format is a popular choice among Python developers due to its readability and simplicity. This format is characterized by a clear separation of sections, which are indicated by section headers. Section headers include Args, Returns, Raises, Yields, and Attributes, among others.

Here's an example of a function documented using the Google Docstring format:

def add_numbers(a, b):
    """
    Adds two numbers together.

    Args:
        a (int): The first number.
        b (int): The second number.

    Returns:
        int: The sum of a and b.
    """
    return a + b

Here, the Args section describes the arguments the function expects, including their type and purpose. The Returns section, on the other hand, describes the result that the function returns, along with its type.

NumPy/SciPy Docstring Format

The NumPy/SciPy Docstring format is another popular format, especially among scientific computing communities. It provides a structured way to document Python code and is characterized by its extensive use of sections and sub-sections, which makes it suitable for documenting complex code.

Here's an example of a function documented using the NumPy/SciPy Docstring format:

def add_numbers(a, b):
    """
    Adds two numbers together.

    Parameters
    ----------
    a : int
        The first number.
    b : int
        The second number.

    Returns
    -------
    int
        The sum of a and b.
    """
    return a + b

In this example, the Parameters section describes the function's parameters, including their type and purpose. The Returns section describes the result that the function returns, along with its type. The use of dashes (------) to separate sections is a distinctive feature of this format.

EpYtext Docstring Format

EpYtext is another popular docstring format used in Python. It's a plain text format for Python docstrings that was developed as part of the Epydoc project. Epytext markup language is designed to be easy to read and write in its raw form, yet easy to render in a variety of output formats.

Here's an example of how to use the EpYtext docstring format:

def add_numbers(a, b):
    """
    This function adds two numbers.

    @param a: The first number.
    @type a: C{int}
    @param b: The second number.
    @type b: C{int}
    @return: The sum of the two numbers.
    @rtype: C{int}
    """
    return a + b

In the above example, you can see that the EpYtext format uses @-style tags to denote different sections of the docstring. The @param and @type tags are used to document the function parameters, while the @return and @rtype tags are used to document the return value of the function.

Choosing the Right Docstring Format

Choosing the right docstring format is largely a matter of personal preference and the specific needs of your project. However, there are a few things to consider when making your decision.

Firstly, consider the complexity of your project. If your project is large and complex, a more structured docstring format like reST or NumPy/SciPy might be beneficial. These formats allow for more detailed documentation, which can be especially helpful in large codebases.

Secondly, consider the tools you're using. Some documentation generation tools, like Sphinx, have better support for certain docstring formats. For example, Sphinx has built-in support for the reST docstring format.

Thirdly, consider the readability of the docstring format. Some developers find certain formats easier to read and write than others. For example, some people find the Google docstring format to be more readable than the reST format.

Here's a quick comparison of the four docstring formats we've discussed:

• reST: Highly structured, great for complex projects, excellent support in Sphinx.
• Google: Less structured, easy to read and write, good support in various tools.
• NumPy/SciPy: Highly structured, great for scientific projects, excellent support in Sphinx.
• EpYtext: Less structured, easy to read and write, good support in Epydoc.

Remember, the most important thing is that you're documenting your code. The specific format you choose is less important than the act of documentation itself.

Conclusion

In this article, we've taken a deep dive into the world of Python docstrings and explored some of the most common formats that developers use to document their code. We've looked at the ReStructured Text (reST), Google, NumPy/SciPy, and Epytext docstring formats, each with their own unique styles and conventions.

Choosing the right docstring format largely depends on your specific project needs and personal preference. Whether you prefer the simplicity of Google's style, the detailed structure of reST, or the mathematical focus of NumPy/SciPy, remember that the key to good documentation is consistency and clarity. As long as your docstrings are clear, concise, and consistent, they will serve as a useful guide for both you and other developers who interact with your code.