Documentation strings, more commonly referred to as docstrings in python are strings that directly document a function. Their presence is checked using :ref:`interrogate-discussion` but the particular format they are written in is checked using darglint.
Once installed darlint can be used to check one of three docstring styles:
For example, consider the file main.py
:
.. literalinclude:: /_static/contributing/discussion/darglint/main.py
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.
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.