darglint performance on Google style docstrings may be too slow to be a pre-commit hook

darglint’s performance on Google-style docstrings is pretty slow on my machine^1. It gets even slower when you try to integrate rst into the docstring.^2 Slow enough that in some cases it’s too much friction as a pre-commit hook (at least on my machine). Posting this both to document my issue and to see if others have ran into this.

Example

"""bar.py"""
def foo():
    """Summary

    Args:
        file (Any):
            A path to a Jupyter Notebook file.
        theme (str): The theme to use for syntax highlighting. May
            be ``'ansi_light'``, ``'ansi_dark'``, or any
            `Pygments theme`_. By default ``'ansi_dark'``.
        plain (bool): Only show plain style. No decorations such as
            boxes or execution counts. If set to pydata`None`
            will autodetect. By default pydata`None`.
        unicode (Optional[bool]): Whether to use unicode characters
            to render the notebook. If set to pydata`None` will
            autodetect. By default pydata`None`.
        hide_output (bool): Do not render the notebook outputs. By
            default pydata`False`.
        nerd_font (bool): Use nerd fonts when appropriate. By
            default pydata`False`.
        files (bool): Create files when needed to render HTML
            content. By default pydata`True`.
        negative_space (bool): Whether render character images in
            negative space. By default pydata`True`.
        hyperlinks (bool): Whether to use hyperlinks. If
            pydata`False` will explicitly print out path. If set
            to pydata`None` will autodetect. By default
            pydata`None`.
        hide_hyperlink_hints (bool): Hide text hints of when content
            is clickable. By default pydata`False`.
        images (Optional[str]): Whether to render images. If set to
            pydata`None` will autodetect. By default
            pydata`None`.
    """
    ...

% darglint bar.py

This example takes 52 seconds on my machine. The example from the issue takes 2:02.^2 This can evolve into a bigger issue—as heavily docstringed commits were timing out on my machine when darglint was ran as a pre-commit hook.

Possible solutions

1. Switch the docstring styles to Sphinx Style
2. Remove darglint as a pre-commit hook (but keep it as a CI linting session)
3. Remove darglint as a default linter from the project

[cjolowicz]

Yes, it seems this option was added for precisely our use case: https://github.com/terrencepreilly/darglint/pull/176

So I guess we could do the following:

1. Exclude darglint from the flake8 hook using --darglint-ignore-regex (your code above)
2. Add a dedicated darglint hook that runs only in the manual stage.
3. Change the Nox session so the manual stage is included when CI is present in the environment.

[paw-lu]

Implimentation attempted in https://github.com/cjolowicz/cookiecutter-hypermodern-python-instance/pull/822.