Package: docsig
Check signature params for proper documentationSupports reStructuredText (Sphinx),NumPy, andGoogleContributingIf you are interested in contributing todocsigplease read about contributinghereInstallation$pipinstalldocsigUsageCommandlineusage: docsig [-h] [-v] [-l] [-c | -C] [-D] [-m] [-o] [-p] [-P] [-i] [-a] [-k]
                         [-n] [-S] [-s STR] [-d LIST] [-t LIST]
                         [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
  -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
  -n, --no-ansi                        disable ansi output
  -S, --summary                        print a summarised report
  -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 targetOptions can also be configured with the pyproject.toml fileIf you find the output is too verbose then the report can be configured to display a summary[tool.docsig]check-dunders=falsecheck-overridden=falsecheck-protected=falsesummary=truedisable=["E101","E102","E103",]target=["E102","E103","E104",]API>>>fromdocsigimportdocsig>>>string="""
... def function(param1, param2, param3) -> None:
...     '''
...
...     :param param1: About param1.
...     :param param2: About param2.
...     :param param3: About param3.
...     '''
...     """>>>docsig(string=string)0>>>string="""
... def function(param1, param2) -> None:
...     '''
...
...     :param param1: About param1.
...     :param param2: About param2.
...     :param param3: About param3.
...     '''
... """>>>docsig(string=string)2-deffunction(✓param1,✓param2,✖None)->✓None:"""
    :param param1: ✓
    :param param2: ✓
    :param param3: ✖
    """<BLANKLINE>E102:includesparametersthatdonotexist(params-do-not-exist)<BLANKLINE>1A full list of checks can be foundhereMessage ControlTo control checksdocsigaccepts disable and enable directivesTo disable individual function checks add an inline comment similar to the example below>>>string="""
... def function_1(param1, param2, param3) -> None:  # docsig: disable
...     '''
...
...     :param param2: Fails.
...     :param param3: Fails.
...     :param param1: Fails.
...     '''
...
... def function_2(param1, param2) -> None:
...     '''
...
...     :param param1: Fails.
...     :param param2: Fails.
...     :param param3: Fails.
...     '''
...
... def function_3(param1, param2, param3) -> None:
...     '''
...
...     :param param1: Fails.
...     :param param2: Fails.
...     '''
... """>>>docsig(string=string)10--deffunction_2(✓param1,✓param2,✖None)->✓None:"""
    :param param1: ✓
    :param param2: ✓
    :param param3: ✖
    """<BLANKLINE>E102:includesparametersthatdonotexist(params-do-not-exist)<BLANKLINE>18--deffunction_3(✓param1,✓param2,✖param3)->✓None:"""
    :param param1: ✓
    :param param2: ✓
    :param None: ✖
    """<BLANKLINE>E103:parametersmissing(params-missing)<BLANKLINE>1To disable all function checks add a module level comment similar to the example below>>>string="""
... # docsig: disable
... def function_1(param1, param2, param3) -> None:
...     '''
...
...     :param param2: Fails.
...     :param param3: Fails.
...     :param param1: Fails.
...     '''
...
... def function_2(param1, param2) -> None:
...     '''
...
...     :param param1: Fails.
...     :param param2: Fails.
...     :param param3: Fails.
...     '''
...
... def function_3(param1, param2, param3) -> None:
...     '''
...
...     :param param1: Fails.
...     :param param2: Fails.
...     '''
... """>>>docsig(string=string)0To disable multiple function checks add a module level disable and enable comment similar to the example below>>>string="""
... # docsig: disable
... def function_1(param1, param2, param3) -> None:
...     '''
...
...     :param param2: Fails.
...     :param param3: Fails.
...     :param param1: Fails.
...     '''
...
... def function_2(param1, param2) -> None:
...     '''
...
...     :param param1: Fails.
...     :param param2: Fails.
...     :param param3: Fails.
...     '''
... # docsig: enable
...
... def function_3(param1, param2, param3) -> None:
...     '''
...
...     :param param1: Fails.
...     :param param2: Fails.
...     '''
... """>>>docsig(string=string)20--deffunction_3(✓param1,✓param2,✖param3)->✓None:"""
    :param param1: ✓
    :param param2: ✓
    :param None: ✖
    """<BLANKLINE>E103:parametersmissing(params-missing)<BLANKLINE>1The same can be done for disabling individual rules>>>string="""
... # docsig: disable=E101
... def function_1(param1, param2, param3) -> int:
...     '''E105.
...
...     :param param1: Fails.
...     :param param2: Fails.
...     :param param3: Fails.
...     '''
...
... def function_2(param1, param2, param3) -> None:  # docsig: disable=E102,E106
...     '''E101,E102,E106.
...
...     :param param1: Fails.
...     :param param1: Fails.
...     :param param2: Fails.
...     :param param3: Fails.
...     '''
...
... def function_3(param1, param2, param3) -> None:
...     '''E101,E102,E106,E107.
...
...     :param param1: Fails.
...     :param param1: Fails.
...     :param param2: Fails.
...     :param: Fails.
...     '''
... """>>>docsig(string=string)3-deffunction_1(✓param1,✓param2,✓param3)->✖int:"""
    :param param1: ✓
    :param param2: ✓
    :param param3: ✓
    :return: ✖
    """<BLANKLINE>E105:returnmissingfromdocstring(return-missing)<BLANKLINE>20--deffunction_3(✓param1,✖param2,✖param3,✖None)->✓None:"""
    :param param1: ✓
    :param param1: ✖
    :param param2: ✖
    :param None: ✖
    """<BLANKLINE>E102:includesparametersthatdonotexist(params-do-not-exist)E106:duplicateparametersfound(duplicate-params-found)E107:parameterappearstobeincorrectlydocumented(param-incorrectly-documented)<BLANKLINE>1Individual rules can also be re-enabledModule level directives will be evaluated separately to inline directives and providing no rules will disable and enable all rules>>>string="""
... # docsig: disable
... def function_1(param1, param2, param3) -> int:
...     '''E105.
...
...     :param param1: Fails.
...     :param param2: Fails.
...     :param param3: Fails.
...     '''
...
... def function_2(param1, param2, param3) -> None:  # docsig: enable=E102,E106
...     '''E101,E102,E106.
...
...     :param param1: Fails.
...     :param param1: Fails.
...     :param param2: Fails.
...     :param param3: Fails.
...     '''
...
... def function_3(param1, param2, param3) -> None:
...     '''E101,E102,E106,E107.
...
...     :param param1: Fails.
...     :param param1: Fails.
...     :param param2: Fails.
...     :param: Fails.
...     '''
... """>>>docsig(string=string)11--deffunction_2(✓param1,✖param2,✖param3,✖None)->✓None:"""
    :param param1: ✓
    :param param1: ✖
    :param param2: ✖
    :param param3: ✖
    """<BLANKLINE>E102:includesparametersthatdonotexist(params-do-not-exist)E106:duplicateparametersfound(duplicate-params-found)<BLANKLINE>1ClassesChecking a class docstring is not enabled by default, as there are two mutually exclusive choices to choose from.This check will either check the documentation of__init__, or check documentation of__init__under the class docstring, and not under__init__itself>>>string="""
... class Klass:
...     def __init__(self, param1, param2) -> None:
...         '''
...
...         :param param1: About param1.
...         :param param2: About param2.
...         :param param3: About param3.
...         '''
... """>>>docsig(string=string,check_class_constructor=True)3inKlass----------classKlass:"""
    :param param1: ✓
    :param param2: ✓
    :param param3: ✖
    """<BLANKLINE>def__init__(✓param1,✓param2,✖None)->✓None:<BLANKLINE>E102:includesparametersthatdonotexist(params-do-not-exist)<BLANKLINE>1>>>string="""
... class Klass:
...     '''
...
...     :param param1: About param1.
...     :param param2: About param2.
...     :param param3: About param3.
...     '''
...     def __init__(self, param1, param2) -> None:
...         pass
... """>>>docsig(string=string,check_class=True)9inKlass----------classKlass:"""
    :param param1: ✓
    :param param2: ✓
    :param param3: ✖
    """<BLANKLINE>def__init__(✓param1,✓param2,✖None)->✓None:<BLANKLINE>E102:includesparametersthatdonotexist(params-do-not-exist)<BLANKLINE>1Checking class docstrings can be permanently enabled in the pyproject.toml file[tool.docsig]check-class-constructor=trueOr[tool.docsig]check-class=truepre-commitdocsigcan be used as apre-commithookIt can be added to your .pre-commit-config.yaml as follows:repos:-repo:https://github.com/jshwi/docsigrev:v0.44.2hooks:-id:docsigargs:-"--check-class"-"--check-dunders"-"--check-overridden"-"--check-protected"-"--summary"