jshwi/docsig

.. image:: https://raw.githubusercontent.com/jshwi/docsig/master/docs/static/docsig.svg
:alt: docsig logo
:width: 50%
:align: center

Check Python signature params for proper documentation

docsig is a Python documentation linter that ensures function and method
signature parameters are properly documented in docstrings. It supports multiple
docstring formats including reStructuredText (Sphinx), NumPy, and
Google styles.

Maintain accurate and up-to-date Python documentation by automatically checking
that all parameters in function signatures match their docstring documentation.
Use docsig as a standalone tool, integrate it with flake8, or add it as a
pre-commit hook to catch documentation issues before they reach your
repository.

Contributing

If you are interested in contributing to docsig, please read about contributing here <https://docsig.io/en/latest/development/contributing.html>__

Installation

.. code-block:: console

$ pip install docsig

Usage

Commandline

.. code-block:: console

usage: docsig [-h] [-V] [-l] [-n] [-v] [--check-class | --check-class-constructor]
              [--check-dunders] [--check-nested] [--check-overridden]
              [--check-property-returns] [--check-protected]
              [--check-protected-class-methods] [--ignore-args] [--ignore-kwargs]
              [--ignore-no-params] [-d LIST] [-t LIST] [-e PATTERN] [-E PATH [PATH ...]]
              [-I] [-s STR]
              [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
  -n, --no-ansi         disable ansi output
  -v, --verbose         increase output verbosity
  --check-class         check class docstrings
  --check-class-constructor
                        check __init__ methods
  --check-dunders       check dunder methods
  --check-nested        check nested functions and classes
  --check-overridden    check overridden methods
  --check-property-returns
                        check property return values
  --check-protected     check protected functions and classes
  --check-protected-class-methods
                        check public methods belonging to protected classes
  --ignore-args         ignore args prefixed with an asterisk
  --ignore-kwargs       ignore kwargs prefixed with two asterisks
  --ignore-no-params    ignore docstrings where parameters are not documented
  -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
  -I, --include-ignored
                        check files even if they match a gitignore pattern
  -s STR, --string STR  string to parse instead of files

Options can also be configured with the pyproject.toml file

.. code-block:: toml

[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

.. code-block:: console

$ flake8 --version
7.3.0 (docsig: 0.81.1, mccabe: 0.7.0, pycodestyle: 2.14.0, pyflakes: 3.4.0) CPython 3.10.19 on Darwin

And now use flake8 to lint your files

.. code-block:: console

$ 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 <https://flake8.pycqa.org/en/latest/user/configuration.html#configuration-locations>_ 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

.. code-block:: ini

[flake8]
sig-check-dunders = True
sig-check-overridden = True
sig-check-protected = True

..
end flake8

API

.. code-block:: python

>>> from docsig import docsig

.. code-block:: python

>>> string = '''
... def function(a, b, c) -> None:
...     """Docstring summary.
...
...     :param a: Description of a.
...     :param b: Description of b.
...     :param c: Description of c.
...     """
... '''
>>> docsig(string=string, no_ansi=True)
0

.. code-block:: python

>>> string = '''
... def function(a, b) -> None:
...     """Docstring summary.
...
...     :param a: Description of a.
...     :param b: Description of b.
...     :param c: Description of c.
...     """
... '''
>>> 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 <https://docsig.io/en/latest/usage/messages.html>__

Message Control

Documentation on message control <https://docsig.io/en/latest/usage/message-control.html>_

Classes

Documenting classes <https://docsig.io/en/latest/usage/configuration.html#classes>_

pre-commit

docsig can be used as a pre-commit <https://pre-commit.com>_ hook

It can be added to your .pre-commit-config.yaml as follows:

Standalone

.. code-block:: yaml

repos:
  - repo: https://github.com/jshwi/docsig
    rev: v0.81.1
    hooks:
      - id: docsig
        args:
          - "--check-class"
          - "--check-dunders"
          - "--check-overridden"
          - "--check-protected"

or integrated with flake8

.. code-block:: yaml

repos:
  - repo: https://github.com/PyCQA/flake8
    rev: "7.1.0"
    hooks:
      - id: flake8
        additional_dependencies:
          - docsig==0.81.1
        args:
          - "--sig-check-class"
          - "--sig-check-dunders"
          - "--sig-check-overridden"
          - "--sig-check-protected"

Check Python signature params for proper documentation

Contributing

Installation

Usage

On this page

Languages

Contributors

Latest Release