maite.testing.docs.validate_docstring#

maite.testing.docs.validate_docstring(obj, ignore=('SA01',), method_ignore=None, property_ignore=None, include_ignored_errors=False, ignore_via_comments_allowed=True)[source]#

Validate an object’s docstring against the NumPy docstring standard [1].

The body of a function or class can include a comment of the format:

# doc-ignore: <CODE1> <CODE2> [...]

where each <CODEN> is any error code listed in the Notes section. This will cause validate_docstring to ignore said error code during its analysis.

When obj is a class object, the __doc__ attributes of obj, obj.__init__ and of all of the public methods and properties of obj will be validated. The doc strings of doc and doc.__init__ are considered in conjunction with one another so that users need not specify redundant documentation.

This function require that numpydoc is installed.

Parameters:
objAny

A function, class, module, or method whose docstring will be validated. If obj is a class, its public methods and properties will be traversed and their doc strings will be included in the validation process.

ignoreCollection[ErrorCode], optional (default=[‘SA01’])

One or more error codes to be excluded from the reported errors. See the Notes section for a list of error codes. NOQA can be specified to ignore all errors.

method_ignoreCollection[ErrorCode] | None

For method docstring. One or more error codes to be excluded from the reported errors. If not specified, defers to the codes specified in ignore.

property_ignoreCollection[ErrorCode] | None

For property doc strings. One or more error codes to be excluded from the reported errors. If not specified, defers to the codes specified in ignore.

include_ignored_errorsbool, optional (default=False)

If True, include the errors that were ignored during the validation.

ignore_via_comments_allowedbool, optional (default=True)

If True then the source code of obj will be parsed for comments of the form # doc-ignore: <CODE1> <CODE2> […] to extract additional error codes that will be ignored during the validation process. Class properties are not supported.

Returns:
NumPyDocResults
A dictionary with the following fields.

  • error_count : int

  • errors : dict[ErrorCode, list[str]]

  • ignored_errors : NotEquired[dict[ErrorCode, list[str]]]

  • file : str

  • file_line : int

Notes

The following are the error codes that can be returned by this validation function: - NOQA: Can be specified to ignore all error codes. - GL01: Docstring text (summary) should start in the line immediately after the opening quotes. - GL02: Closing quotes should be placed in the line after the last text in the docstring. - GL03: Double line break found. - GL05: Tabs found at the start of line. - GL06: Found unknown section. - GL07: Sections are in the wrong order. - 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. - 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. - SS06: Summary should fit in a single line. - ES01: No extended summary found. - PR01: Signature parameter not documented. - PR02: Unknown parameters included in Parameters. - PR03: Wrong parameters order. - PR04: Parameter has no type - PR05: Parameter type should not finish with “.”. - PR06: Parameter type should be changed. - PR07: Parameter has no description. - PR08: Parameter description should start with a capital letter. - PR09: Parameter description should finish with “.”. - PR10: Parameter requires a space before the colon. - RT01: No Returns section found - RT02: The first line of the Returns section should contain only the type. - 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. - SA03: Description should be capitalized for See Also reference. - SA04: Missing description for See Also reference. - EX01: No examples section found.

References

Examples

>>> from maite.testing.docs import validate_docstring
>>> from maite.testing.documentation.documentation_dependencies import person

Let’s ignore the need for an Extended Summary and a See Also section.

>>> validate_docstring(person, ignore=('ES01', 'SA01'), include_ignored_errors=True)
{'error_count': 0, 'errors': {}, ...'ignored_errors': {'ES01': ['No extended summary found'], 'SA01': ['See Also section not found']}...

Using comments to skip validation.

>>> def f():
...     # doc-ignore: GL08
...     return
>>> validate_docstring(f)   
{'error_count': 0, 'errors': {}, 'file': ..., 'file_line': 1}
>>> validate_docstring(f, ignore_via_comments_allowed=False)   
{'error_count': 1, 'errors': {'GL08': ['The object does not have a docstring']}, 'file': ..., 'file_line': 1}