Metadata-Version: 2.1
Name: docsig
Version: 0.17.0
Summary: Check signature params for proper documentation
Home-page: https://pypi.org/project/docsig/
License: MIT
Keywords: docstring,signature,params,check,docs
Author: jshwi
Author-email: stephen@jshwisolutions.com
Maintainer: jshwi
Maintainer-email: stephen@jshwisolutions.com
Requires-Python: >=3.8,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Requires-Dist: astroid (>=2.11.6,<3.0.0)
Requires-Dist: object-colors (>=2.1.0,<3.0.0)
Requires-Dist: tomli (>=2.0.1,<3.0.0)
Project-URL: Documentation, https://docsig.readthedocs.io/en/latest/?badge=latest
Project-URL: Repository, https://github.com/jshwi/docsig
Description-Content-Type: text/x-rst

docsig
======
.. 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://img.shields.io/pypi/v/docsig
    :alt: pypi
.. image:: https://github.com/jshwi/docsig/actions/workflows/ci.yml/badge.svg
    :target: https://github.com/jshwi/docsig/actions/workflows/ci.yml
    :alt: CI
.. 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

Check signature params for proper documentation
-----------------------------------------------

Currently only supports reStructuredText (Sphinx)

Installation
------------

.. code-block:: console

    $ pip install docsig

Usage
-----

Commandline
***********

.. code-block:: console

    usage: docsig [-h] [-v] [-c] [-s STR] [-d LIST] [-t LIST] [path [path ...]]

    Check docstring matches signature

    positional arguments:
      path                     directories or files to check (default: .)

    optional arguments:
      -h, --help               show this help message and exit
      -v, --version            show version and exit
      -c, --check-class        check class docstrings and constructors
      -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

Options can also be configured with the pyproject.toml file

.. code-block:: toml

    [tool.docsig]
    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:
    ...     '''Summary for passing docstring...
    ...
    ...     Explanation for passing docstring...
    ...
    ...     :param param1: About param1.
    ...     :param param2: About param2.
    ...     :param param3: About param3.
    ...     '''
    ...     """
    >>> docsig(string=string)
    0

.. code-block:: python

    >>> string = """
    ... def function(param1, param2) -> None:
    ...     '''Summary for failing docstring...
    ...
    ...     Explanation for failing docstring...
    ...
    ...     :param param1: About param1.
    ...     :param param2: About param2.
    ...     :param param3: About param3.
    ...     '''
    ... """
    >>> docsig(string=string)
    2
    -
    def function(✓param1, ✓param2, ✖None) -> ✓None:
        """...
    <BLANKLINE>
        :param param1: ✓
        :param param2: ✓
        :param param3: ✖
        """
    <BLANKLINE>
    E102: includes parameters that do not exist
    <BLANKLINE>
    1


There are currently 9 other `errors <https://docsig.readthedocs.io/en/latest/docsig.html#docsig-messages>`_

Classes
#######
Checking a class docstring is not enabled by default, as this check is opinionated, and won't suite everyone

This check will check documentation of `__init__` under the class docstring, and not under `__init__` itself

.. code-block:: python

    >>> string = """
    ...     class Klass:
    ...         '''Summary for failing docstring...
    ...
    ...         Explanation for failing docstring...
    ...
    ...         :param param1: About param1.
    ...         :param param2: About param2.
    ...         :param param3: About param3.
    ...         '''
    ...         def __init__(param1, param2) -> None:
    ...             pass
    ... """
    >>> docsig(string=string, check_class=True)
    Klass::11
    ---------
    class Klass:
        """...
    <BLANKLINE>
        :param param1: ✓
        :param param2: ✓
        :param param3: ✖
        """
    <BLANKLINE>
        def __init__(✓param1, ✓param2, ✖None) -> ✓None:
    <BLANKLINE>
    E102: includes parameters that do not exist
    <BLANKLINE>
    1

Checking class docstrings can be permanently enabled in the pyproject.toml file

.. code-block:: toml

    [tool.docsig]
    check-class = true

