flake8-rst-docstrings

0.4.0 · active · verified Thu Apr 16

flake8-rst-docstrings is an MIT-licensed plugin for Flake8 that validates Python docstring markup as reStructuredText (RST). It leverages the `docutils` library and `restructuredtext-lint` internally to perform checks, ensuring that docstrings conform to RST syntax. The library is actively maintained, with its current version being 0.4.0, and development tracked on GitHub.

Common errors

```
RST301: Unexpected indentation.
```
cause Docstring content does not follow reStructuredText indentation rules, or an unexpected unindent occurred.

fix Correct the indentation in your docstring to adhere to reStructuredText syntax. Ensure consistent spacing and proper nesting for lists, blocks, etc.
```
RST303: Unknown directive type "XXX".
```
cause The docstring uses a reStructuredText directive (e.g., `.. XXX::`) that is not recognized by `docutils`, often a Sphinx-specific directive not configured for the linter.

fix If using Sphinx-specific directives, add them to your `flake8` configuration file using the `rst-directives` option (e.g., `rst-directives = envvar, exception, seealso`).
```
RST304: Unknown interpreted text role "XXX".
```
cause The docstring uses an interpreted text role (e.g., `:XXX:`) not recognized by `docutils`, typically a Sphinx-specific role.

fix If using Sphinx-specific roles, add them to your `flake8` configuration file using the `rst-roles` option (e.g., `rst-roles = class, func, ref`).
```
RST213: Inline strong start-string without end-string.
```
cause A reStructuredText inline markup (like `**bold text**` or `*italic text*`) is missing its closing delimiter.

fix Ensure all inline markup in your docstrings has matching start and end delimiters (e.g., `**strong**`, ``literal``, `*emphasis*`).

Warnings

breaking Python 2.7 support was dropped in versions newer than 0.0.14. Python 3.8 or later is now required.
Fix: Upgrade to Python 3.8+ or use version 0.0.14 if Python 2.7 support is strictly necessary.
gotcha When using Google Python Style docstrings, `flake8-rst-docstrings` may report unwanted warnings (e.g., RST307) because Google style is not strict reStructuredText until processed by tools like Sphinx's Napoleon extension. This can lead to false positives.
Fix: Add specific RST violation codes to your `flake8` configuration file's `extend-ignore` list (e.g., `extend-ignore = RST307`) to suppress these warnings.
gotcha Docutils, used internally for RST validation, often only provides a line number for the start of a paragraph rather than the exact line where an issue occurs. This can make pinpointing the precise location of an error more challenging.
Fix: Review the entire docstring section indicated by the warning, paying close attention to reStructuredText syntax within that block.
gotcha Some IDEs (like older VSCode Python extensions) might not properly display linter entries from `flake8` plugins using 3-character codes (like 'RST') by default. This is due to how the IDE's embedded linter might interact with external `flake8` installations.
Fix: Configure your IDE's Python extension to prioritize the workspace-installed `flake8` by setting an option like `'flake8.importStrategy': 'fromEnvironment'` in your settings.json.

Install

pip install flake8-rst-docstrings Install with pip

Quickstart

After installing, flake8-rst-docstrings automatically integrates with flake8. Simply run flake8 on your Python files. You can configure additional RST roles, directives, or ignore specific checks in your flake8 configuration file (e.g., .flake8, setup.cfg, pyproject.toml).

import os

def example_function(param1: str, param2: int):
    """This is an example docstring.

    :param param1: The first parameter.
    :type param1: str
    :param param2: The second parameter.
    :type param2: int
    :raises ValueError: If param2 is negative.
    :return: A concatenated string.
    :rtype: str

    .. warning:: This is a reStructuredText warning.
    """
    if param2 < 0:
        raise ValueError("param2 cannot be negative")
    return f"{param1}-{param2}"


# To run flake8, save the above code as 'example.py' and execute:
# flake8 example.py

view raw JSON →