Supports reStructuredText (Sphinx
), NumPy
, and Google
If you are interested in contributing to docsig
please read about contributing here
$ pip install docsig
usage: docsig [-h] [-V] [-l] [-c | -C] [-D] [-m] [-N] [-o] [-p] [-P] [-i] [-a] [-k] [-T]
[-I] [-n] [-v] [-s STR] [-d LIST] [-t LIST] [-e PATTERN]
[path [path ...]]
Check signature params for proper documentation
positional arguments:
path directories or files to check
optional arguments:
-h, --help show this help message and exit
-V, --version show program's version number and exit
-l, --list-checks display a list of all checks and their messages
-c, --check-class check class docstrings
-C, --check-class-constructor check __init__ methods. Note: mutually incompatible
with -c
-D, --check-dunders check dunder methods
-m, --check-protected-class-methods check public methods belonging to protected classes
-N, --check-nested check nested functions and classes
-o, --check-overridden check overridden methods
-p, --check-protected check protected functions and classes
-P, --check-property-returns check property return values
-i, --ignore-no-params ignore docstrings where parameters are not
documented
-a, --ignore-args ignore args prefixed with an asterisk
-k, --ignore-kwargs ignore kwargs prefixed with two asterisks
-T, --ignore-typechecker ignore checking return values
-I, --include-ignored check files even if they match a gitignore pattern
-n, --no-ansi disable ansi output
-v, --verbose increase output verbosity
-s STR, --string STR string to parse instead of files
-d LIST, --disable LIST comma separated list of rules to disable
-t LIST, --target LIST comma separated list of rules to target
-e PATTERN, --exclude PATTERN regular expression of files or dirs to exclude from
checks
Options can also be configured with the pyproject.toml file
[tool.docsig]
check-dunders = false
check-overridden = false
check-protected = false
disable = [
"E101",
"E102",
"E103",
]
target = [
"E102",
"E103",
"E104",
]
>>> from docsig import docsig
>>> string = """
... def function(param1, param2, param3) -> None:
... '''
...
... :param param1: About param1.
... :param param2: About param2.
... :param param3: About param3.
... '''
... """
>>> docsig(string=string, no_ansi=True)
0
>>> string = """
... def function(param1, param2) -> None:
... '''
...
... :param param1: About param1.
... :param param2: About param2.
... :param param3: About param3.
... '''
... """
>>> docsig(string=string, no_ansi=True)
2 in function
E102: includes parameters that do not exist (params-do-not-exist)
1
A full list of checks can be found here
Documentation on message control
docsig
can be used as a pre-commit hook
It can be added to your .pre-commit-config.yaml as follows:
repos:
- repo: https://github.com/jshwi/docsig
rev: v0.53.3
hooks:
- id: docsig
args:
- "--check-class"
- "--check-dunders"
- "--check-overridden"
- "--check-protected"