Skip to main content

Check signature params for proper documentation

Project description


docsig logo

License PyPI CI CodeQL pre-commit.ci status codecov.io readthedocs.org python3.8 Black isort docformatter pylint Security Status Known Vulnerabilities docsig

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] [-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 checks

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

Flake8

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.60.0, mccabe: 0.7.0, pycodestyle: 2.12.0, pyflakes: 3.2.0) CPython 3.8.13 on Darwin

And 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

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
    SIG202: includes parameters that do not exist (params-do-not-exist)
1

A full list of checks can be found here

Message Control

If you have been using docsig prior to v0.56.0, please see updated messages

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:

Standalone

repos:
  - repo: https://github.com/jshwi/docsig
    rev: v0.60.0
    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.60.0
        args:
          - "--sig-check-class"
          - "--sig-check-dunders"
          - "--sig-check-overridden"
          - "--sig-check-protected"

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.60.0.tar.gz (25.7 kB view hashes)

Uploaded Source

Built Distribution

docsig-0.60.0-py3-none-any.whl (28.6 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page