jshwi/docsig

Check signature params for proper documentation

Check signature params for proper documentation

Supports reStructuredText (Sphinx), NumPy, and Google

Contributing

If you are interested in contributing to docsig please read about contributing here

Installation

$ pip install docsig

Usage

Commandline

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",
]

API

>>> 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

Message Control

Documentation on message control

Classes

Documenting classes

pre-commit

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.54.1
    hooks:
      - id: docsig
        args:
          - "--check-class"
          - "--check-dunders"
          - "--check-overridden"
          - "--check-protected"