Check signature params for proper documentation
Project description
Check signature params for proper documentation
Currently only supports reStructuredText (Sphinx)
Installation
$ pip install docsig
Usage
Commandline
usage: docsig [-h] [-v] [-c] [-s STR] [-d LIST] [-t LIST] [path [path ...]]
Check docstring matches signature
positional arguments:
path directories or files to check (default: .)
optional arguments:
-h, --help show this help message and exit
-v, --version show version and exit
-c, --check-class check class docstrings and constructors
-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
Options can also be configured with the pyproject.toml file
[tool.docsig]
disable = [
"E101",
"E102",
"E103",
]
target = [
"E102",
"E103",
"E104",
]
API
>>> from docsig import docsig
>>> string = """
... def function(param1, param2, param3) -> None:
... '''Summary for passing docstring...
...
... Explanation for passing docstring...
...
... :param param1: About param1.
... :param param2: About param2.
... :param param3: About param3.
... '''
... """
>>> docsig(string=string)
0
>>> string = """
... def function(param1, param2) -> None:
... '''Summary for failing docstring...
...
... Explanation for failing docstring...
...
... :param param1: About param1.
... :param param2: About param2.
... :param param3: About param3.
... '''
... """
>>> docsig(string=string)
2
-
def function(✓param1, ✓param2, ✖None) -> ✓None:
"""...
<BLANKLINE>
:param param1: ✓
:param param2: ✓
:param param3: ✖
"""
<BLANKLINE>
E102: includes parameters that do not exist
<BLANKLINE>
1
There are currently 9 other errors
Classes
Checking a class docstring is not enabled by default, as this check is opinionated, and won’t suite everyone
This check will check documentation of __init__ under the class docstring, and not under __init__ itself
>>> string = """
... class Klass:
... '''Summary for failing docstring...
...
... Explanation for failing docstring...
...
... :param param1: About param1.
... :param param2: About param2.
... :param param3: About param3.
... '''
... def __init__(param1, param2) -> None:
... pass
... """
>>> docsig(string=string, check_class=True)
Klass::11
---------
class Klass:
"""...
<BLANKLINE>
:param param1: ✓
:param param2: ✓
:param param3: ✖
"""
<BLANKLINE>
def __init__(✓param1, ✓param2, ✖None) -> ✓None:
<BLANKLINE>
E102: includes parameters that do not exist
<BLANKLINE>
1
Checking class docstrings can be permanently enabled in the pyproject.toml file
[tool.docsig]
check-class = true
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
docsig-0.17.0.tar.gz
(13.7 kB
view hashes)
Built Distribution
docsig-0.17.0-py3-none-any.whl
(15.1 kB
view hashes)