Validation#
Docstring Validation using Pre-Commit Hook#
To enable validation of docstrings as you commit files, add the
following to your .pre-commit-config.yaml
file:
- repo: https://github.com/numpy/numpydoc
rev: <version>
hooks:
- id: numpydoc-validation
After installing numpydoc
, run the following to see available
command line options for this hook:
$ numpydoc lint --help
Using a config file provides additional customization. Both pyproject.toml
and setup.cfg
are supported; however, if the project contains both
you must use the pyproject.toml
file. The example below configures
the pre-commit hook as follows:
checks
: Report findings on all checks exceptEX01
,SA01
, andES01
(using the same logic as the validation during Sphinx build fornumpydoc_validation_checks
).exclude
: Don’t report issues on objects matching any of the regular expressions\.undocumented_method$
or\.__repr__$
. This maps tonumpydoc_validation_exclude
from the Sphinx build configuration.override_SS05
: Allow docstrings to start with “Process “, “Assess “, or “Access “. To override different checks, add a field for each code in the form ofoverride_<code>
with a collection of regular expression(s) to search for in the contents of a docstring, not the object name. This maps tonumpydoc_validation_overrides
from the Sphinx build configuration.
pyproject.toml
:
[tool.numpydoc_validation]
checks = [
"all", # report on all checks, except the below
"EX01",
"SA01",
"ES01",
]
# remember to use single quotes for regex in TOML
exclude = [ # don't report on objects that match any of these regex
'\.undocumented_method$',
'\.__repr__$',
]
override_SS05 = [ # override SS05 to allow docstrings starting with these words
'^Process ',
'^Assess ',
'^Access ',
]
setup.cfg
:
[tool:numpydoc_validation]
checks = all,EX01,SA01,ES01
exclude = \.undocumented_method$,\.__repr__$
override_SS05 = ^Process ,^Assess ,^Access ,
In addition to the above, inline ignore comments can be used to ignore findings on a case by case basis.
If any issues are found when committing, a report is printed out, and the commit is halted:
numpydoc-validation......................................................Failed
- hook id: numpydoc-validation
- exit code: 1
+----------------------+----------------------+---------+--------------------------------------+
| file | item | check | description |
+======================+======================+=========+======================================+
| src/pkg/utils.py:1 | utils | GL08 | The object does not have a docstring |
| src/pkg/utils.py:90 | utils.normalize | PR04 | Parameter "field" has no type |
| src/pkg/module.py:12 | module.MyClass | GL08 | The object does not have a docstring |
| src/pkg/module.py:33 | module.MyClass.parse | RT03 | Return value has no description |
+----------------------+----------------------+---------+--------------------------------------+
See below for a full listing of checks.
Docstring Validation using Python#
To see the Restructured Text generated for an object, the numpydoc
module
can be called. For example, to do it for numpy.ndarray
, use:
$ numpydoc validate numpy.ndarray
This will validate that the docstring can be built.
For an exhaustive validation of the formatting of the docstring, use the
validate
subcommand. This will report the errors detected, such as
incorrect capitalization, wrong order of the sections, and many other
issues. Note that this will honor inline ignore comments,
but will not look for any configuration like the pre-commit hook
or Sphinx extension do.
Docstring Validation during Sphinx Build#
It is also possible to run docstring validation as part of the Sphinx build
process.
This behavior is controlled by the numpydoc_validation_checks
configuration
parameter in conf.py
.
For example, to verify that all of the parameters in the function signature
are accounted for in the Parameters
section of the docstring, add the
following line to conf.py
:
numpydoc_validation_checks = {"PR01"}
This will cause a Sphinx warning to be raised for any (non-module) docstring that has undocumented parameters in the signature. The full set of validation checks can be activated by:
numpydoc_validation_checks = {"all"}
The complete validation suite contains many checks
including some for style, capitalization, and grammar.
It is unlikely that reporting all validation warnings is desirable for
most use-cases.
Individual checks can be excluded by including them in the set with the
special keyword "all"
:
# Report warnings for all validation checks except GL01, GL02, and GL05
numpydoc_validation_checks = {"all", "GL01", "GL02", "GL05"}
In addition, you can exclude any findings on certain objects with
numpydoc_validation_exclude
, which maps to exclude
in the
pre-commit hook setup:
# don't report on objects that match any of these regex
numpydoc_validation_exclude = [
'\.undocumented_method$',
'\.__repr__$',
]
Overrides based on docstring contents are also supported, but the structure is slightly different than the pre-commit hook setup:
numpydoc_validation_overrides = {
"SS02": [ # override SS05 to allow docstrings starting with these words
'^Process ',
'^Assess ',
'^Access ',
]
}
Ignoring Validation Checks with Inline Comments#
Sometimes you only want to ignore a specific check or set of checks for a specific piece of code. This level of fine-tuned control is provided via inline comments:
class SomeClass: # numpydoc ignore=EX01,SA01,ES01
"""This is the docstring for SomeClass."""
def __init__(self): # numpydoc ignore=GL08
pass
This is supported by the CLI, pre-commit hook, and Sphinx extension.
Built-in Validation Checks#
The numpydoc.validation
module provides a mapping with all of the checks
that are run as part of the validation procedure.
The mapping is of the form: error_code : <explanation>
where error_code
provides a shorthand for the check being run, and <explanation>
provides
a more detailed message. For example:
"EX01" : "No examples section found"
The full mapping of validation checks is given below.
ERROR_MSGS = {
"GL01": "Docstring text (summary) should start in the line immediately "
"after the opening quotes (not in the same line, or leaving a "
"blank line in between)",
"GL02": "Closing quotes should be placed in the line after the last text "
"in the docstring (do not close the quotes in the same line as "
"the text, or leave a blank line between the last text and the "
"quotes)",
"GL03": "Double line break found; please use only one blank line to "
"separate sections or paragraphs, and do not leave blank lines "
"at the end of docstrings",
"GL05": 'Tabs found at the start of line "{line_with_tabs}", please use '
"whitespace only",
"GL06": 'Found unknown section "{section}". Allowed sections are: '
"{allowed_sections}",
"GL07": "Sections are in the wrong order. Correct order is: {correct_sections}",
"GL08": "The object does not have a docstring",
"GL09": "Deprecation warning should precede extended summary",
"GL10": "reST directives {directives} must be followed by two colons",
"SS01": "No summary found (a short summary in a single line should be "
"present at the beginning of the docstring)",
"SS02": "Summary does not start with a capital letter",
"SS03": "Summary does not end with a period",
"SS04": "Summary contains heading whitespaces",
"SS05": "Summary must start with infinitive verb, not third person "
'(e.g. use "Generate" instead of "Generates")',
"SS06": "Summary should fit in a single line",
"ES01": "No extended summary found",
"PR01": "Parameters {missing_params} not documented",
"PR02": "Unknown parameters {unknown_params}",
"PR03": "Wrong parameters order. Actual: {actual_params}. "
"Documented: {documented_params}",
"PR04": 'Parameter "{param_name}" has no type',
"PR05": 'Parameter "{param_name}" type should not finish with "."',
"PR06": 'Parameter "{param_name}" type should use "{right_type}" instead '
'of "{wrong_type}"',
"PR07": 'Parameter "{param_name}" has no description',
"PR08": 'Parameter "{param_name}" description should start with a '
"capital letter",
"PR09": 'Parameter "{param_name}" description should finish with "."',
"PR10": 'Parameter "{param_name}" requires a space before the colon '
"separating the parameter name and type",
"RT01": "No Returns section found",
"RT02": "The first line of the Returns section should contain only the "
"type, unless multiple values are being returned",
"RT03": "Return value has no description",
"RT04": "Return value description should start with a capital letter",
"RT05": 'Return value description should finish with "."',
"YD01": "No Yields section found",
"SA01": "See Also section not found",
"SA02": "Missing period at end of description for See Also "
'"{reference_name}" reference',
"SA03": "Description should be capitalized for See Also "
'"{reference_name}" reference',
"SA04": 'Missing description for See Also "{reference_name}" reference',
"EX01": "No examples section found",
}