Supports reStructuredText (Sphinx), NumPy, and Google
If you are interested in contributing to docsig please read about contributing here
$ pip install docsigusage: 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] [-E PATH [PATH ...]]
[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
-E PATH [PATH ...], --excludes PATH [PATH ...]
path glob patterns to exclude from checksOptions can also be configured with the pyproject.toml file
[tool.docsig]
check-dunders = false
check-overridden = false
check-protected = false
disable = [
"SIG101",
"SIG102",
"SIG402",
]
target = [
"SIG202",
"SIG203",
"SIG201",
]docsig can also be used as a flake8 plugin. Install flake8 and
ensure your installation has registered docsig
$ flake8 --version
7.1.0 (docsig: 0.64.1, mccabe: 0.7.0, pycodestyle: 2.12.0, pyflakes: 3.2.0) CPython 3.8.13 on DarwinAnd now use flake8 to lint your files
$ flake8 example.py
example.py:1:1: SIG202 includes parameters that do not exist (params-do-not-exist) 'function'With flake8 the pyproject.toml config will still be the base config, though the
ini files flake8 gets it config from will override the pyproject.toml config.
For flake8 all args and config options are prefixed with sig to
avoid any potential conflicts with other plugins
[flake8]
sig-check-dunders = True
sig-check-overridden = True
sig-check-protected = True>>> 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
SIG202: includes parameters that do not exist (params-do-not-exist)
1A full list of checks can be found here
If you have been using docsig prior to v0.56.0, please see
updated messages
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:
Standalone
repos:
- repo: https://github.com/jshwi/docsig
rev: v0.64.1
hooks:
- id: docsig
args:
- "--check-class"
- "--check-dunders"
- "--check-overridden"
- "--check-protected"or integrated with flake8
repos:
- repo: https://github.com/PyCQA/flake8
rev: "7.1.0"
hooks:
- id: flake8
additional_dependencies:
- docsig==0.64.1
args:
- "--sig-check-class"
- "--sig-check-dunders"
- "--sig-check-overridden"
- "--sig-check-protected"