Registry / testing / flake8-rst-docstrings

flake8-rst-docstrings

library0.4.0pypypiunverified

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.

testing

pip install flake8-rst-docstrings

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · FLAKE8-RST-DOCSTRI

flake8-rst-docstrings

testingpythonv0.4.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

Debug

Known issues

breakingPython 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.

affects: >0.0.14

gotchaWhen 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.

affects: All

gotchaDocutils, 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.

affects: All

gotchaSome 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.

affects: All (depending on IDE/extension version)

Errors

Common errors & fixes

RST301: Unexpected indentation.

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".

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".

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.

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*`).

Upgrade

Version history

0.4.0latest on PyPI · released Oct 6, 2025

Audit

Dependencies

flake8requiredCore linter that this package plugs into.

docutilsrequiredUsed internally for reStructuredText parsing and validation.

restructuredtext-lintrequiredUsed internally for reStructuredText linting logic.

pygmentsrequiredListed as a required dependency in PyPI metadata for some functionalities.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/peterjc/flake8-rst-docstrings ↗

packagehttps://pypi.org/project/flake8-rst-docstrings/ ↗

docshttps://github.com/peterjc/flake8-rst-docstrings/blob/master/README.rst ↗