3 Different Docstring Formats for Python

 


Python is becoming a popular programming language nowadays. For any coding project, documentation is the most important part for increasing the readability of code but at the same time most ignored part too! To solve this, the Sphinx tool comes in handy which automates the documentation part, if you aren’t aware of this tool, have a look at this.

Now that you’re aware of Sphinx and know how to use it. Let us know the most commonly used docstring formats out there in the wild, which are namely- Google, NumPy, and Sphinx docstring formats.

1. Google Docstring

This docstring format is recommended by Khan Academy and is popularly known as “Google Docstring”. To make sure the docstring is compatible with Sphinx and is recognized by Sphinx’s autodoc, add the sphinx.ext.napoleon extension in the conf.py file. The docstring format is:

def google_docstrings(num1, num2
                      ) -> int:
    """Add up two integer numbers.

    This function simply wraps the ``+`` operator, and does not
    do anything interesting, except for illustrating what
    the docstring of a very simple function looks like.

    Args:
        num1 (int) : First number to add.
        num2 (int) : Second number to add.

    Returns:
        The sum of ``num1`` and ``num2``.

    Raises:
        AnyError: If anything bad happens.
    """
    return num1 + num2
The output generated by Sphinx looks like this:
To make life easier if you’re using VS Code, you can install this extension. This extension lays the boilerplate for the docstrings and you only need to add the description of each parameter.

2. NumPy Docstring

This documentation format is used in major data science libraries like NumPy, SciPy, and Pandas. Just like Google’s docstring, to make it compatible with Sphinx you’ve to add the sphinx.ext.napoleon extension in the conf.py file. The format for docstring is:

def numpy_docstrings(num1, num2) -> int:
    """
    Add up two integer numbers.

    This function simply wraps the ``+`` operator, and does not
    do anything interesting, except for illustrating what
    the docstring of a very simple function looks like.

    Parameters
    ----------
    num1 : int
        First number to add.
    num2 : int
        Second number to add.

    Returns
    -------
    int
        The sum of ``num1`` and ``num2``.

    Raises
    ======
     MyException
        if anything bad happens

    See Also
    --------
    subtract : Subtract one integer from another.

    Examples
    --------
    >>> add(2, 2)
    4
    >>> add(25, 0)
    25
    >>> add(10, -10)
    0
    """
    return num1 + num2
The output for the same is:

Google Vs NumPy’s Docstrings:

The output for both docstrings looks similar, the main difference between the two styles is that Google uses indentation to separate sections, whereas NumPy uses underlines. NumPy style tends to require more vertical space, whereas Google-style tends to use more horizontal space. Google-style tends to be easier to read for short and simple docstrings, whereas NumPy-style tends to be easier to read for long and in-depth docstrings.

3. Sphinx Docstring

Nothing better than the good old sphinx docstring, this is the most basic docstring format that is used but is somewhat visually dense which makes it hard to read. The format for the same is:
def sphinx_docstrings(num1, num2) -> int:
    """Add up two integer numbers.

    This function simply wraps the ``+`` operator, and does not
    do anything interesting, except for illustrating what
    the docstring of a very simple function looks like.

    :param int num1: First number to add.
    :param int num2: Second number to add.
    :returns:  The sum of ``num1`` and ``num2``.
    :rtype: int
    :raises AnyError: If anything bad happens.
    """
    return num1 + num2
The output looks like this:

To experiment with the different formats, clone this repository. Once cloned, play around with the formats and run the make clean html followed by make html inside of docs folder to regenerate the HTML files.

Conclusion

Other than the above formats, there are many docstring formats that can be used for Python and we don’t have a single winner in this game.
So choose whichever format you’re comfortable with, do not mix the formats, and stick with it throughout the project. My personal favorite is NumPy’s Docstring!