pydoclint

Docstring linter that checks whether the parameters, return values and exceptions match the function/class signature. Supports three docstring styles: NumPy, Google and Sphinx.

pydoclint is a flake8 plugin, so when installed into your environment, it will also show when you run flake8 on code with docstrings (the warnings beginning “DOC”).

PyPI View on PyPI GitHub View on GitHub

Example Quarto .qmd file:

1:     ---
2:     title: "Example"
3:     ---
4:     
5:     This file contains an example of a function with docstring issues.
6:     
7:     ```{python}
8:     def add(a, b):
9:         """
10:        Add two numbers.
11:    
12:        Parameters
13:        ----------
14:        a : str
15:        """
16:        return a + b
17:    ```

Run pydoclint using lintquarto

lintquarto -l pydoclint -p docstring_example.qmd
Skipping files that match this pattern: \.git|\.tox
/home/runner/work/lintquarto/lintquarto/docs/pages/tools/examples/docstring_example.qmd
/home/runner/work/lintquarto/lintquarto/docs/pages/tools/examples/docstring_example.qmd
    8: DOC101: Function `add`: Docstring contains fewer arguments than in function signature.
    8: DOC106: Function `add`: The option `--arg-type-hints-in-signature` is `True` but there are no argument type hints in the signature
    8: DOC107: Function `add`: The option `--arg-type-hints-in-signature` is `True` but not all args in the signature have type hints
    8: DOC103: Function `add`: Docstring arguments are different from function arguments. (Or could be other formatting issues: https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in the docstring: [b: ].
    8: DOC201: Function `add` does not have a return section in docstring