Darglint can be used as a Flake8 plugin. To use it, ensure both flake8 and darglint are installed in the same environment. Darglint will automatically use your Flake8 configuration.

Note that settings like docstring_style must be placed under the [flake8] section of your configuration file, not a [darglint] section.

[flake8]
strictness=short
docstring_style=sphinx

To run Darglint automatically before every commit, add it to your .pre-commit-config.yaml file.

repos:
-   repo: https://github.com/terrencepreilly/darglint
    rev: master
    hooks:
    - id: darglint

You can install darglint directly from PyPI using pip. Alternatively, you can install it from a local clone of the repository.

pip install darglint

Or from a local clone

pip install .

The strictness setting controls how rigorously darglint validates docstrings. There are three levels:

• short: Allows one-line descriptions. Any docstring longer than one line is fully checked.
• long: Allows one-line descriptions and descriptions that lack arguments/returns/yields sections. Anything more is fully checked.
• full (Default): All docstrings are fully checked against the implementation.

[darglint]
strictness=short

Darglint categorizes errors into specific groups based on the type of documentation issue. These error codes (e.g., DAR101) are used to identify the nature of the mismatch between a Python function definition and its docstring.

Error Groups:

• 000 Style: General documentation style issues.
• 100 Args: Issues related to function arguments.
• 200 Returns: Issues related to return values.
• 300 Yields: Issues related to generator yields.
• 400 Raises: Issues related to exceptions raised.
• 500 Variables: Issues related to variable descriptions.

If certain exceptions do not need to be explicitly documented in the docstring's raises section, you can specify them using the ignore_raise key in your configuration file.

[darglint]
ignore_raise=ValueError,MyCustomError

Darglint supports different docstring formats. You can specify the style via the CLI or in a configuration file.

Supported Styles:

• sphinx: Imposes restrictions like all fields (e.g., :returns:) being the last items and using four-space indents.
• numpy: Initial implementation; currently considered unstable.

Configuration via CLI: Use the -s or --docstring-style flag.

Configuration via Config File: Use the docstring_style key in your configuration file (e.g., .darglint, setup.cfg, or tox.ini).

# In a config file
[darglint]
docstring_style=sphinx

# Via CLI
darglint -s numpy example.py

You can customize the output format of error messages using message_template and specify which docstring format to validate against using docstring_style.

Supported styles include google (default), sphinx, and numpy.

[darglint]
# Custom message format (e.g., DAR102@driver.py:72)
message_template={msg_id}@{path}:{line}

# Set docstring style to sphinx
docstring_style=sphinx

The Strictness enum defines the minimum intensity with which darglint applies docstring checks. It does not determine if a check is applied, but rather how deep or strict that check is. If a docstring exceeds the requirements of the chosen level, darglint assumes everything must be checked.

Available levels:

• SHORT_DESCRIPTION: Allows a single-line description.
• LONG_DESCRIPTION: Allows a single-line description followed by a long description, but does not require specific sections.
• FULL_DESCRIPTION: Requires a complete docstring including all expected sections.

from darglint.strictness import Strictness

# Example usage of levels
level = Strictness.SHORT_DESCRIPTION

Darglint provides multiple ways to ignore specific docstring errors:

1. Global Configuration: Errors can be added to config.errors_to_ignore to be suppressed everywhere.
2. Inline # noqa comments: You can suppress specific errors directly in the docstring using # noqa: <ERROR_CODE>.
   • If a # noqa: <ERROR_CODE> is present but has no specific identifier following it, it ignores all instances of that error code for that docstring.
   • You can also ignore specific instances of an error code by providing the identifier (e.g., the parameter name) in the noqa comment.
3. Regex/Property Skipping: The checker skips functions entirely if they match config.ignore_regex or if they are properties and config.ignore_properties is enabled.