{"id":18608523,"url":"https://github.com/jshwi/docsig","last_synced_at":"2026-04-01T22:22:05.561Z","repository":{"id":37433187,"uuid":"504735230","full_name":"jshwi/docsig","owner":"jshwi","description":"Check signature params for proper documentation","archived":false,"fork":false,"pushed_at":"2024-04-22T11:48:29.000Z","size":1590,"stargazers_count":25,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-04-22T13:33:11.882Z","etag":null,"topics":["check","ci","compare","docstring","document","function","google","numpy","parameters","pre-commit","pyproject","python","signature","sphinx","test","tool"],"latest_commit_sha":null,"homepage":"https://docsig.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jshwi.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-06-18T03:35:49.000Z","updated_at":"2024-07-28T05:20:12.831Z","dependencies_parsed_at":"2022-07-14T07:10:32.486Z","dependency_job_id":"ce768340-7add-464a-b0a1-8b02483004b6","html_url":"https://github.com/jshwi/docsig","commit_stats":null,"previous_names":[],"tags_count":98,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jshwi%2Fdocsig","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jshwi%2Fdocsig/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jshwi%2Fdocsig/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jshwi%2Fdocsig/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jshwi","download_url":"https://codeload.github.com/jshwi/docsig/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248309338,"owners_count":21082195,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["check","ci","compare","docstring","document","function","google","numpy","parameters","pre-commit","pyproject","python","signature","sphinx","test","tool"],"created_at":"2024-11-07T03:03:18.109Z","updated_at":"2026-04-01T22:22:05.550Z","avatar_url":"https://github.com/jshwi.png","language":"Python","readme":"|\n\n.. image:: https://raw.githubusercontent.com/jshwi/docsig/master/docs/static/docsig.svg\n   :alt: docsig logo\n   :width: 50%\n   :align: center\n\n|\n\n|License| |PyPI| |CI| |CodeQL| |pre-commit.ci status| |codecov.io| |readthedocs.org| |python3.10| |Black| |isort| |pylint| |Security Status| |Known Vulnerabilities|\n\n.. |License| image:: https://img.shields.io/badge/License-MIT-yellow.svg\n   :target: https://opensource.org/licenses/MIT\n   :alt: License\n.. |PyPI| image:: https://img.shields.io/pypi/v/docsig\n   :target: https://pypi.org/project/docsig/\n   :alt: PyPI\n.. |CI| image:: https://github.com/jshwi/docsig/actions/workflows/build.yaml/badge.svg\n   :target: https://github.com/jshwi/docsig/actions/workflows/build.yaml\n   :alt: CI\n.. |CodeQL| image:: https://github.com/jshwi/docsig/actions/workflows/codeql-analysis.yml/badge.svg\n   :target: https://github.com/jshwi/docsig/actions/workflows/codeql-analysis.yml\n   :alt: CodeQL\n.. |pre-commit.ci status| image:: https://results.pre-commit.ci/badge/github/jshwi/docsig/master.svg\n   :target: https://results.pre-commit.ci/latest/github/jshwi/docsig/master\n   :alt: pre-commit.ci status\n.. |codecov.io| image:: https://codecov.io/gh/jshwi/docsig/branch/master/graph/badge.svg\n   :target: https://codecov.io/gh/jshwi/docsig\n   :alt: codecov.io\n.. |readthedocs.org| image:: https://readthedocs.org/projects/docsig/badge/?version=latest\n   :target: https://docsig.io/en/latest/?badge=latest\n   :alt: readthedocs.org\n.. |python3.10| image:: https://img.shields.io/badge/python-3.10-blue.svg\n   :target: https://www.python.org/downloads/release/python-390\n   :alt: python3.10\n.. |Black| image:: https://img.shields.io/badge/code%20style-black-000000.svg\n   :target: https://github.com/psf/black\n   :alt: Black\n.. |isort| image:: https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat\u0026labelColor=ef8336\n   :target: https://pycqa.github.io/isort/\n   :alt: isort\n.. |pylint| image:: https://img.shields.io/badge/linting-pylint-yellowgreen\n   :target: https://github.com/PyCQA/pylint\n   :alt: pylint\n.. |Security Status| image:: https://img.shields.io/badge/security-bandit-yellow.svg\n   :target: https://github.com/PyCQA/bandit\n   :alt: Security Status\n.. |Known Vulnerabilities| image:: https://snyk.io/test/github/jshwi/docsig/badge.svg\n   :target: https://snyk.io/test/github/jshwi/docsig/badge.svg\n   :alt: Known Vulnerabilities\n\nCheck Python signature params for proper documentation\n-------------------------------------------------------\n\n**docsig** is a Python documentation linter that ensures function and method\nsignature parameters are properly documented in docstrings. It supports multiple\ndocstring formats including reStructuredText (``Sphinx``), ``NumPy``, and\n``Google`` styles.\n\nMaintain accurate and up-to-date Python documentation by automatically checking\nthat all parameters in function signatures match their docstring documentation.\nUse docsig as a standalone tool, integrate it with ``flake8``, or add it as a\n``pre-commit`` hook to catch documentation issues before they reach your\nrepository.\n\nContributing\n------------\nIf you are interested in contributing to ``docsig``, please read about contributing `here \u003chttps://docsig.io/en/latest/development/contributing.html\u003e`__\n\nInstallation\n------------\n\n.. code-block:: console\n\n    $ pip install docsig\n\nUsage\n-----\n\nCommandline\n***********\n\n.. code-block:: console\n\n    usage: docsig [-h] [-V] [-l] [-n] [-v] [--check-class | --check-class-constructor]\n                  [--check-dunders] [--check-nested] [--check-overridden]\n                  [--check-property-returns] [--check-protected]\n                  [--check-protected-class-methods] [--ignore-args] [--ignore-kwargs]\n                  [--ignore-no-params] [-d LIST] [-t LIST] [-e PATTERN] [-E PATH [PATH ...]]\n                  [-I] [-s STR]\n                  [path [path ...]]\n\n    Check signature params for proper documentation\n\n    positional arguments:\n      path                  directories or files to check\n\n    optional arguments:\n      -h, --help            show this help message and exit\n      -V, --version         show program's version number and exit\n      -l, --list-checks     display a list of all checks and their messages\n      -n, --no-ansi         disable ansi output\n      -v, --verbose         increase output verbosity\n      --check-class         check class docstrings\n      --check-class-constructor\n                            check __init__ methods\n      --check-dunders       check dunder methods\n      --check-nested        check nested functions and classes\n      --check-overridden    check overridden methods\n      --check-property-returns\n                            check property return values\n      --check-protected     check protected functions and classes\n      --check-protected-class-methods\n                            check public methods belonging to protected classes\n      --ignore-args         ignore args prefixed with an asterisk\n      --ignore-kwargs       ignore kwargs prefixed with two asterisks\n      --ignore-no-params    ignore docstrings where parameters are not documented\n      -d LIST, --disable LIST\n                            comma separated list of rules to disable\n      -t LIST, --target LIST\n                            comma separated list of rules to target\n      -e PATTERN, --exclude PATTERN\n                            regular expression of files or dirs to exclude from checks\n      -E PATH [PATH ...], --excludes PATH [PATH ...]\n                            path glob patterns to exclude from checks\n      -I, --include-ignored\n                            check files even if they match a gitignore pattern\n      -s STR, --string STR  string to parse instead of files\n\nOptions can also be configured with the pyproject.toml file\n\n.. code-block:: toml\n\n    [tool.docsig]\n    check-dunders = false\n    check-overridden = false\n    check-protected = false\n    disable = [\n        \"SIG101\",\n        \"SIG102\",\n        \"SIG402\",\n    ]\n    target = [\n        \"SIG202\",\n        \"SIG203\",\n        \"SIG201\",\n    ]\n\nFlake8\n******\n\n``docsig`` can also be used as a ``flake8`` plugin. Install ``flake8`` and\nensure your installation has registered `docsig`\n\n.. code-block:: console\n\n    $ flake8 --version\n    7.3.0 (docsig: 0.81.3, mccabe: 0.7.0, pycodestyle: 2.14.0, pyflakes: 3.4.0) CPython 3.10.19 on Darwin\n\nAnd now use `flake8` to lint your files\n\n.. code-block:: console\n\n    $ flake8 example.py\n    example.py:1:1: SIG202 includes parameters that do not exist (params-do-not-exist) 'function'\n\nWith ``flake8`` the pyproject.toml config will still be the base config, though the\n`ini files \u003chttps://flake8.pycqa.org/en/latest/user/configuration.html#configuration-locations\u003e`_ ``flake8`` gets it config from will override the pyproject.toml config.\nFor ``flake8`` all args and config options are prefixed with ``sig`` to\navoid any potential conflicts with other plugins\n\n.. code-block:: ini\n\n    [flake8]\n    sig-check-dunders = True\n    sig-check-overridden = True\n    sig-check-protected = True\n\n..\n   end flake8\n\nAPI\n***\n\n.. code-block:: python\n\n    \u003e\u003e\u003e from docsig import docsig\n\n.. code-block:: python\n\n    \u003e\u003e\u003e string = '''\n    ... def function(a, b, c) -\u003e None:\n    ...     \"\"\"Docstring summary.\n    ...\n    ...     :param a: Description of a.\n    ...     :param b: Description of b.\n    ...     :param c: Description of c.\n    ...     \"\"\"\n    ... '''\n    \u003e\u003e\u003e docsig(string=string, no_ansi=True)\n    0\n\n.. code-block:: python\n\n    \u003e\u003e\u003e string = '''\n    ... def function(a, b) -\u003e None:\n    ...     \"\"\"Docstring summary.\n    ...\n    ...     :param a: Description of a.\n    ...     :param b: Description of b.\n    ...     :param c: Description of c.\n    ...     \"\"\"\n    ... '''\n    \u003e\u003e\u003e docsig(string=string, no_ansi=True)\n    2 in function\n        SIG202: includes parameters that do not exist (params-do-not-exist)\n    1\n\nA full list of checks can be found `here \u003chttps://docsig.io/en/latest/usage/messages.html\u003e`__\n\nMessage Control\n***************\n\n`Documentation on message control \u003chttps://docsig.io/en/latest/usage/message-control.html\u003e`_\n\nClasses\n*******\n\n`Documenting classes \u003chttps://docsig.io/en/latest/usage/configuration.html#classes\u003e`_\n\npre-commit\n**********\n\n``docsig`` can be used as a `pre-commit \u003chttps://pre-commit.com\u003e`_ hook\n\nIt can be added to your .pre-commit-config.yaml as follows:\n\nStandalone\n\n.. code-block:: yaml\n\n    repos:\n      - repo: https://github.com/jshwi/docsig\n        rev: v0.81.3\n        hooks:\n          - id: docsig\n            args:\n              - \"--check-class\"\n              - \"--check-dunders\"\n              - \"--check-overridden\"\n              - \"--check-protected\"\n\nor integrated with ``flake8``\n\n.. code-block:: yaml\n\n    repos:\n      - repo: https://github.com/PyCQA/flake8\n        rev: \"7.1.0\"\n        hooks:\n          - id: flake8\n            additional_dependencies:\n              - docsig==0.81.3\n            args:\n              - \"--sig-check-class\"\n              - \"--sig-check-dunders\"\n              - \"--sig-check-overridden\"\n              - \"--sig-check-protected\"\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjshwi%2Fdocsig","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjshwi%2Fdocsig","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjshwi%2Fdocsig/lists"}