{"id":4751,"library":"rstcheck","title":"reStructuredText and Code Block Linter","description":"rstcheck is a CLI application and Python library designed to check the syntax of reStructuredText (RST) documents and code blocks embedded within them. It leverages docutils for RST parsing and includes optional support for Sphinx and TOML configuration. The project follows semantic versioning and has an active release cadence, with the current stable version being 6.2.5.","status":"active","version":"6.2.5","language":"en","source_language":"en","source_url":"https://github.com/rstcheck/rstcheck","tags":["linter","restructuredtext","rst","static analysis","code quality"],"install":[{"cmd":"pip install rstcheck","lang":"bash","label":"Core library"},{"cmd":"pip install rstcheck[sphinx]","lang":"bash","label":"With Sphinx support"},{"cmd":"pip install rstcheck[toml]","lang":"bash","label":"With TOML configuration support"}],"dependencies":[{"reason":"Required for Sphinx-specific RST checks and directives.","package":"sphinx","optional":true},{"reason":"Required for parsing TOML-formatted configuration files (e.g., pyproject.toml).","package":"tomli","optional":true}],"imports":[{"note":"The primary programmatic interface for linting content.","symbol":"check","correct":"import rstcheck\nresults = list(rstcheck.check('...'))"}],"quickstart":{"code":"import rstcheck\n\nrst_content_good = \"\"\"\nExample\n=======\n\nThis is a valid reStructuredText document.\n\n.. code:: python\n\n    print('Hello, world!')\n\"\"\"\n\nrst_content_bad = \"\"\"\nBad Example\n===========\n\nThis document has bad RST syntax.\n\n.. code:: python\n\n    print('Missing quote)\n\"\"\"\n\n# Check good content\nresults_good = list(rstcheck.check(rst_content_good))\nprint(f\"Good content issues: {results_good}\")\n\n# Check bad content\nresults_bad = list(rstcheck.check(rst_content_bad))\nprint(f\"Bad content issues: {results_bad}\")\n\n# Alternatively, via CLI (requires saving to a file):\n# Create a temporary file for CLI example\nwith open('bad_example.rst', 'w') as f:\n    f.write(rst_content_bad)\nimport subprocess\nresult_cli = subprocess.run(['rstcheck', 'bad_example.rst'], capture_output=True, text=True)\nprint(f\"\\nCLI Output:\\n{result_cli.stdout}{result_cli.stderr}\")\nimport os\nos.remove('bad_example.rst')","lang":"python","description":"This quickstart demonstrates how to use `rstcheck` programmatically with the `rstcheck.check()` function to lint reStructuredText strings, both valid and invalid. It also shows how to invoke it as a command-line tool, which is its primary use case."},"warnings":[{"fix":"Review the 'Migration-Guides' in the official documentation, specifically 'Version 5 to 6'. Update CLI arguments (e.g., `--report` to `--report-level`, `--ignore-language` to `--ignore-languages`), and adjust configuration file keys (e.g., `report` to `report_level`, `ignore_language` to `ignore_languages`).","message":"Version 6 introduced significant breaking changes. The codebase was restructured, with the core logic moved to `rstcheck-core`. The main repository changed from `myint/rstcheck` to `rstcheck/rstcheck`. CLI options and configuration file keys were renamed, and CLI options now overwrite config file settings. Numeric `report` levels are no longer supported.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"If using `rstcheck.check()` programmatically, ensure all necessary configurations (like `ignore_directives`, `ignore_roles`, `ignore_messages`, `report_level`) are passed directly as arguments to the `check()` function, or use the CLI for automated config file detection.","message":"When using `rstcheck.check()` as a module, it does not load any configuration files automatically, as this could mutate docutils registries. This means that custom configurations (e.g., ignored directives, roles) will not apply unless explicitly passed.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Organize your configuration according to the precedence rules. For `pyproject.toml`, ensure settings are within `[tool.rstcheck]`. Be aware that CLI arguments will override any corresponding settings in config files. Use `--warn-unknown-settings` CLI flag to get warnings about unrecognized settings in config files.","message":"rstcheck's configuration file detection prioritizes `.rstcheck.cfg`, then `pyproject.toml`, then `setup.cfg`. Within `pyproject.toml`, settings must be under the `[tool.rstcheck]` section. CLI options always take precedence over configuration file settings.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When ignoring specific errors using `--ignore-messages` or `ignore_messages` in configuration, provide precise Python regular expressions to match the desired messages. Understand that the granularity of error filtering is limited by `docutils`'s output.","message":"rstcheck relies on `docutils` for parsing reStructuredText. This means it inherits `docutils`'s limitations and error reporting style. Error messages are filtered at a textual level using Python regex, as `docutils` doesn't categorize errors beyond general levels (info, warning, error, severe).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}