Checking the format of docstrings with darglint

Documentation strings, more commonly referred to as docstrings in python are strings that directly document a function. Their presence is checked using Checking the presence of docstrings with interrogate but the particular format they are written in is checked using darglint.

Once installed darglint can be used to check one of three docstring styles:

1. Google style guide

2. Sphinx style guide

3. Numpy style guide

For example, consider the file main.py:

def get_mean(collection):
    """
    Obtain the average of a collection of objects.

    Parameters
    ----------
    collection : list
        A list of numbers

    Returns
    -------
    float
        The mean of the numbers.
    """
    return sum(collection) / len(collection)

After installing darglint:

$ python -m pip install darglint

If we check the format of this file against the Google style guide:

$ darglint -s google main.py
main.py:get_mean:1: DAR101: - collection
main.py:get_mean:1: DAR201: - return

we get two errors, we can cross reference the error codes DAR101 and DAR201 at https://github.com/terrencepreilly/darglint#error-codes.

• DAR101: “The docstring is missing a parameter in the definition.”

• DAR201: “The docstring is missing a return from definition.”

Note that our file does have both those things but here darglint is telling us that they do not match with the google style guide.

If we check the format of this file against the Sphinx style guide:

$ darglint -s sphinx main.py
main.py:get_mean:1: DAR101: - collection
main.py:get_mean:1: DAR201: - return

we get the same two errors.

Running, the file against the Numpy style guide gives:

$ darglint -s numpy main.py
$

No errors are raised as this is indeed written using the Numpy style guide which is also the convention chosen for the entire Nashpy source code.

Running darglint as part of the test suite

If darglint is installed it will automatically run as part of the flake8 check. For Nashpy this is done as part of the pytest run which is all configured using tox.