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.
pip install rstcheckVerified import paths — ran on the pinned version, not inferred.
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.
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`).
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.
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.
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.