Validation

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:

$ python -m numpydoc numpy.ndarray

This will validate that the docstring can be built.

For an exhaustive validation of the formatting of the docstring, use the --validate parameter. This will report the errors detected, such as incorrect capitalization, wrong order of the sections, and many other issues.

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"}

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',