{"id":7234,"library":"flake8-rst-docstrings","title":"flake8-rst-docstrings","description":"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.","status":"active","version":"0.4.0","language":"en","source_language":"en","source_url":"https://github.com/peterjc/flake8-rst-docstrings","tags":["flake8","linting","docstrings","reStructuredText","RST","validation","sphinx"],"install":[{"cmd":"pip install flake8-rst-docstrings","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core linter that this package plugs into.","package":"flake8","optional":false},{"reason":"Used internally for reStructuredText parsing and validation.","package":"docutils","optional":false},{"reason":"Used internally for reStructuredText linting logic.","package":"restructuredtext-lint","optional":false},{"reason":"Listed as a required dependency in PyPI metadata for some functionalities.","package":"pygments","optional":false}],"imports":[],"quickstart":{"code":"import os\n\ndef example_function(param1: str, param2: int):\n    \"\"\"This is an example docstring.\n\n    :param param1: The first parameter.\n    :type param1: str\n    :param param2: The second parameter.\n    :type param2: int\n    :raises ValueError: If param2 is negative.\n    :return: A concatenated string.\n    :rtype: str\n\n    .. warning:: This is a reStructuredText warning.\n    \"\"\"\n    if param2 < 0:\n        raise ValueError(\"param2 cannot be negative\")\n    return f\"{param1}-{param2}\"\n\n\n# To run flake8, save the above code as 'example.py' and execute:\n# flake8 example.py","lang":"python","description":"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)."},"warnings":[{"fix":"Upgrade to Python 3.8+ or use version 0.0.14 if Python 2.7 support is strictly necessary.","message":"Python 2.7 support was dropped in versions newer than 0.0.14. Python 3.8 or later is now required.","severity":"breaking","affected_versions":">0.0.14"},{"fix":"Add specific RST violation codes to your `flake8` configuration file's `extend-ignore` list (e.g., `extend-ignore = RST307`) to suppress these warnings.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Review the entire docstring section indicated by the warning, paying close attention to reStructuredText syntax within that block.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All (depending on IDE/extension version)"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Correct the indentation in your docstring to adhere to reStructuredText syntax. Ensure consistent spacing and proper nesting for lists, blocks, etc.","cause":"Docstring content does not follow reStructuredText indentation rules, or an unexpected unindent occurred.","error":"RST301: Unexpected indentation."},{"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`).","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.","error":"RST303: Unknown directive type \"XXX\"."},{"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`).","cause":"The docstring uses an interpreted text role (e.g., `:XXX:`) not recognized by `docutils`, typically a Sphinx-specific role.","error":"RST304: Unknown interpreted text role \"XXX\"."},{"fix":"Ensure all inline markup in your docstrings has matching start and end delimiters (e.g., `**strong**`, ``literal``, `*emphasis*`).","cause":"A reStructuredText inline markup (like `**bold text**` or `*italic text*`) is missing its closing delimiter.","error":"RST213: Inline strong start-string without end-string."}]}