docsig 0.79.0
Check signature params for proper documentation
License: MIT
Requires Python: <4.0,>=3.10
Keywords: check, docs, docstring, params, signature

|

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

|

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

.. |License| image:: https://img.shields.io/badge/License-MIT-yellow.svg
   :target: https://opensource.org/licenses/MIT
   :alt: License
.. |PyPI| image:: https://img.shields.io/pypi/v/docsig
   :target: https://pypi.org/project/docsig/
   :alt: PyPI
.. |CI| image:: https://github.com/jshwi/docsig/actions/workflows/build.yaml/badge.svg
   :target: https://github.com/jshwi/docsig/actions/workflows/build.yaml
   :alt: CI
.. |CodeQL| image:: https://github.com/jshwi/docsig/actions/workflows/codeql-analysis.yml/badge.svg
   :target: https://github.com/jshwi/docsig/actions/workflows/codeql-analysis.yml
   :alt: CodeQL
.. |pre-commit.ci status| image:: https://results.pre-commit.ci/badge/github/jshwi/docsig/master.svg
   :target: https://results.pre-commit.ci/latest/github/jshwi/docsig/master
   :alt: pre-commit.ci status
.. |codecov.io| image:: https://codecov.io/gh/jshwi/docsig/branch/master/graph/badge.svg
   :target: https://codecov.io/gh/jshwi/docsig
   :alt: codecov.io
.. |readthedocs.org| image:: https://readthedocs.org/projects/docsig/badge/?version=latest
   :target: https://docsig.io/en/latest/?badge=latest
   :alt: readthedocs.org
.. |python3.10| image:: https://img.shields.io/badge/python-3.10-blue.svg
   :target: https://www.python.org/downloads/release/python-390
   :alt: python3.10
.. |Black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
   :target: https://github.com/psf/black
   :alt: Black
.. |isort| image:: https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336
   :target: https://pycqa.github.io/isort/
   :alt: isort
.. |pylint| image:: https://img.shields.io/badge/linting-pylint-yellowgreen
   :target: https://github.com/PyCQA/pylint
   :alt: pylint
.. |Security Status| image:: https://img.shields.io/badge/security-bandit-yellow.svg
   :target: https://github.com/PyCQA/bandit
   :alt: Security Status
.. |Known Vulnerabilities| image:: https://snyk.io/test/github/jshwi/docsig/badge.svg
   :target: https://snyk.io/test/github/jshwi/docsig/badge.svg
   :alt: Known Vulnerabilities

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] [--ignore-typechecker] [-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
      --ignore-typechecker  ignore checking return values
      -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.79.0, 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.79.0
        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.79.0
            args:
              - "--sig-check-class"
              - "--sig-check-dunders"
              - "--sig-check-overridden"
              - "--sig-check-protected"