|
.. image:: https://raw.githubusercontent.com/jshwi/docsig/master/docs/static/docsig.svg
:alt: docsig logo
:width: 50%
:align: center
|
.. image:: https://img.shields.io/badge/License-MIT-yellow.svg
:target: https://opensource.org/licenses/MIT
:alt: License
.. image:: https://img.shields.io/pypi/v/docsig
:target: https://pypi.org/project/docsig/
:alt: PyPI
.. image:: https://github.com/jshwi/docsig/actions/workflows/build.yaml/badge.svg
:target: https://github.com/jshwi/docsig/actions/workflows/build.yaml
:alt: CI
.. 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
.. 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
.. image:: https://codecov.io/gh/jshwi/docsig/branch/master/graph/badge.svg
:target: https://codecov.io/gh/jshwi/docsig
:alt: codecov.io
.. image:: https://readthedocs.org/projects/docsig/badge/?version=latest
:target: https://docsig.readthedocs.io/en/latest/?badge=latest
:alt: readthedocs.org
.. image:: https://img.shields.io/badge/python-3.8-blue.svg
:target: https://www.python.org/downloads/release/python-380
:alt: python3.8
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
:alt: Black
.. image:: https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336
:target: https://pycqa.github.io/isort/
:alt: isort
.. image:: https://img.shields.io/badge/%20formatter-docformatter-fedcba.svg
:target: https://github.com/PyCQA/docformatter
:alt: docformatter
.. image:: https://img.shields.io/badge/linting-pylint-yellowgreen
:target: https://github.com/PyCQA/pylint
:alt: pylint
.. image:: https://img.shields.io/badge/security-bandit-yellow.svg
:target: https://github.com/PyCQA/bandit
:alt: Security Status
.. image:: https://snyk.io/test/github/jshwi/docsig/badge.svg
:target: https://snyk.io/test/github/jshwi/docsig/badge.svg
:alt: Known Vulnerabilities
.. image:: https://snyk.io/advisor/python/docsig/badge.svg
:target: https://snyk.io/advisor/python/docsig
:alt: 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 <https://github.com/jshwi/docsig/blob/master/CONTRIBUTING.md>`__
Installation
------------
.. code-block:: console
$ pip install docsig
Usage
-----
Commandline
***********
.. code-block:: console
usage: docsig [-h] [-V] [-l] [-c | -C] [-D] [-m] [-N] [-o] [-p] [-P] [-i] [-a]
[-k] [-n] [-S] [-v] [-s STR] [-d LIST] [-t LIST] [-e EXCLUDE]
[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
-n, --no-ansi disable ansi output
-S, --summary print a summarised report
-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
If you find the output is too verbose then the report can be configured to display a summary
.. code-block:: toml
[tool.docsig]
check-dunders = false
check-overridden = false
check-protected = false
summary = true
disable = [
"E101",
"E102",
"E103",
]
target = [
"E102",
"E103",
"E104",
]
API
***
.. code-block:: python
>>> from docsig import docsig
.. code-block:: python
>>> string = """
... def function(param1, param2, param3) -> None:
... '''
...
... :param param1: About param1.
... :param param2: About param2.
... :param param3: About param3.
... '''
... """
>>> docsig(string=string, summary=True, no_ansi=True)
0
.. code-block:: python
>>> string = """
... def function(param1, param2) -> None:
... '''
...
... :param param1: About param1.
... :param param2: About param2.
... :param param3: About param3.
... '''
... """
>>> docsig(string=string, summary=True, 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 <https://docsig.readthedocs.io/en/latest/docsig.html#docsig-messages>`__
Message Control
***************
`Documentation on message control <https://github.com/jshwi/docsig/blob/master/docs/examples/message-control.rst>`_
Classes
*******
`Documenting classes <https://github.com/jshwi/docsig/blob/master/docs/examples/classes.rst>`_
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:
.. code-block:: yaml
repos:
- repo: https://github.com/jshwi/docsig
rev: v0.49.1
hooks:
- id: docsig
args:
- "--check-class"
- "--check-dunders"
- "--check-overridden"
- "--check-protected"
- "--summary"
Raw data
{
"_id": null,
"home_page": "https://pypi.org/project/docsig/",
"name": "docsig",
"maintainer": "jshwi",
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": "stephen@jshwisolutions.com",
"keywords": "check, docs, docstring, params, signature",
"author": "jshwi",
"author_email": "stephen@jshwisolutions.com",
"download_url": "https://files.pythonhosted.org/packages/d8/7d/7a1eb5ec9a1964b4130930b286eb2a058d97858970144b6009a580fb1a8c/docsig-0.49.1.tar.gz",
"platform": null,
"description": "|\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.. image:: https://img.shields.io/badge/License-MIT-yellow.svg\n :target: https://opensource.org/licenses/MIT\n :alt: License\n.. image:: https://img.shields.io/pypi/v/docsig\n :target: https://pypi.org/project/docsig/\n :alt: PyPI\n.. 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.. 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.. 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.. 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.. image:: https://readthedocs.org/projects/docsig/badge/?version=latest\n :target: https://docsig.readthedocs.io/en/latest/?badge=latest\n :alt: readthedocs.org\n.. image:: https://img.shields.io/badge/python-3.8-blue.svg\n :target: https://www.python.org/downloads/release/python-380\n :alt: python3.8\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://github.com/psf/black\n :alt: Black\n.. image:: https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336\n :target: https://pycqa.github.io/isort/\n :alt: isort\n.. image:: https://img.shields.io/badge/%20formatter-docformatter-fedcba.svg\n :target: https://github.com/PyCQA/docformatter\n :alt: docformatter\n.. image:: https://img.shields.io/badge/linting-pylint-yellowgreen\n :target: https://github.com/PyCQA/pylint\n :alt: pylint\n.. image:: https://img.shields.io/badge/security-bandit-yellow.svg\n :target: https://github.com/PyCQA/bandit\n :alt: Security Status\n.. 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.. image:: https://snyk.io/advisor/python/docsig/badge.svg\n :target: https://snyk.io/advisor/python/docsig\n :alt: docsig\n\nCheck signature params for proper documentation\n-----------------------------------------------\n\nSupports reStructuredText (``Sphinx``), ``NumPy``, and ``Google``\n\nContributing\n------------\nIf you are interested in contributing to ``docsig`` please read about contributing `here <https://github.com/jshwi/docsig/blob/master/CONTRIBUTING.md>`__\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] [-c | -C] [-D] [-m] [-N] [-o] [-p] [-P] [-i] [-a]\n [-k] [-n] [-S] [-v] [-s STR] [-d LIST] [-t LIST] [-e EXCLUDE]\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 -c, --check-class check class docstrings\n -C, --check-class-constructor check __init__ methods. Note: mutually\n incompatible with -c\n -D, --check-dunders check dunder methods\n -m, --check-protected-class-methods check public methods belonging to protected\n classes\n -N, --check-nested check nested functions and classes\n -o, --check-overridden check overridden methods\n -p, --check-protected check protected functions and classes\n -P, --check-property-returns check property return values\n -i, --ignore-no-params ignore docstrings where parameters are not\n documented\n -a, --ignore-args ignore args prefixed with an asterisk\n -k, --ignore-kwargs ignore kwargs prefixed with two asterisks\n -n, --no-ansi disable ansi output\n -S, --summary print a summarised report\n -v, --verbose increase output verbosity\n -s STR, --string STR string to parse instead of files\n -d LIST, --disable LIST comma separated list of rules to disable\n -t LIST, --target LIST comma separated list of rules to target\n -e PATTERN, --exclude PATTERN regular expression of files or dirs to exclude\n from checks\n\nOptions can also be configured with the pyproject.toml file\n\nIf you find the output is too verbose then the report can be configured to display a summary\n\n.. code-block:: toml\n\n [tool.docsig]\n check-dunders = false\n check-overridden = false\n check-protected = false\n summary = true\n disable = [\n \"E101\",\n \"E102\",\n \"E103\",\n ]\n target = [\n \"E102\",\n \"E103\",\n \"E104\",\n ]\n\nAPI\n***\n\n.. code-block:: python\n\n >>> from docsig import docsig\n\n.. code-block:: python\n\n >>> string = \"\"\"\n ... def function(param1, param2, param3) -> None:\n ... '''\n ...\n ... :param param1: About param1.\n ... :param param2: About param2.\n ... :param param3: About param3.\n ... '''\n ... \"\"\"\n >>> docsig(string=string, summary=True, no_ansi=True)\n 0\n\n.. code-block:: python\n\n >>> string = \"\"\"\n ... def function(param1, param2) -> None:\n ... '''\n ...\n ... :param param1: About param1.\n ... :param param2: About param2.\n ... :param param3: About param3.\n ... '''\n ... \"\"\"\n >>> docsig(string=string, summary=True, no_ansi=True)\n 2 in function\n E102: includes parameters that do not exist (params-do-not-exist)\n 1\n\nA full list of checks can be found `here <https://docsig.readthedocs.io/en/latest/docsig.html#docsig-messages>`__\n\nMessage Control\n***************\n\n`Documentation on message control <https://github.com/jshwi/docsig/blob/master/docs/examples/message-control.rst>`_\n\nClasses\n*******\n\n`Documenting classes <https://github.com/jshwi/docsig/blob/master/docs/examples/classes.rst>`_\n\npre-commit\n**********\n\n``docsig`` can be used as a `pre-commit <https://pre-commit.com>`_ hook\n\nIt can be added to your .pre-commit-config.yaml as follows:\n\n.. code-block:: yaml\n\n repos:\n - repo: https://github.com/jshwi/docsig\n rev: v0.49.1\n hooks:\n - id: docsig\n args:\n - \"--check-class\"\n - \"--check-dunders\"\n - \"--check-overridden\"\n - \"--check-protected\"\n - \"--summary\"\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Check signature params for proper documentation",
"version": "0.49.1",
"project_urls": {
"Documentation": "https://docsig.readthedocs.io/en/latest",
"Homepage": "https://pypi.org/project/docsig/",
"Repository": "https://github.com/jshwi/docsig"
},
"split_keywords": [
"check",
" docs",
" docstring",
" params",
" signature"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ed166dca3d36a675f7b1fcdc0432585a53a00e526a52dc8daeea2bbda91e3d33",
"md5": "f06b9454dca84cb14062ae04a7cc2e25",
"sha256": "73a4a28d22b970b607fba17859abb891f34f4aea16f14a200093b6e698a1f78d"
},
"downloads": -1,
"filename": "docsig-0.49.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f06b9454dca84cb14062ae04a7cc2e25",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 24475,
"upload_time": "2024-04-20T06:19:24",
"upload_time_iso_8601": "2024-04-20T06:19:24.194922Z",
"url": "https://files.pythonhosted.org/packages/ed/16/6dca3d36a675f7b1fcdc0432585a53a00e526a52dc8daeea2bbda91e3d33/docsig-0.49.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d87d7a1eb5ec9a1964b4130930b286eb2a058d97858970144b6009a580fb1a8c",
"md5": "365d15120199780c504a612ca72872e6",
"sha256": "944a07effd870d6154ca38217dff174c021900c277d2373c175bd6aba240a198"
},
"downloads": -1,
"filename": "docsig-0.49.1.tar.gz",
"has_sig": false,
"md5_digest": "365d15120199780c504a612ca72872e6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 21109,
"upload_time": "2024-04-20T06:19:27",
"upload_time_iso_8601": "2024-04-20T06:19:27.360039Z",
"url": "https://files.pythonhosted.org/packages/d8/7d/7a1eb5ec9a1964b4130930b286eb2a058d97858970144b6009a580fb1a8c/docsig-0.49.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-20 06:19:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jshwi",
"github_project": "docsig",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "docsig"
}
JSON
