Registry / testing / rstcheck

rstcheck

JSON →
library6.3.0pypypi✓ verified 24d ago

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 rstcheck
INSTALL
IMPORT
SIG · RSTCHECK
R
rstcheck
testingpythonv6.3.0
Install
5.9s avg
Import
Disk
45MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v6.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.915 runs
installs and imports cleanly · install 0.0s · import 0.000s · 46.1MB
glibc
py 3.103.915 runs
installs and imports cleanly · install 5.9s · import 0.000s · 46MB
45MB installed
● package 45MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

check
import rstcheck
from rstcheck import check

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.

import rstcheck rst_content_good = """ Example ======= This is a valid reStructuredText document. .. code:: python print('Hello, world!') """ rst_content_bad = """ Bad Example =========== This document has bad RST syntax. .. code:: python print('Missing quote) """ # Check good content results_good = list(rstcheck.check(rst_content_good)) print(f"Good content issues: {results_good}") # Check bad content results_bad = list(rstcheck.check(rst_content_bad)) print(f"Bad content issues: {results_bad}") # Alternatively, via CLI (requires saving to a file): # Create a temporary file for CLI example with open('bad_example.rst', 'w') as f: f.write(rst_content_bad) import subprocess result_cli = subprocess.run(['rstcheck', 'bad_example.rst'], capture_output=True, text=True) print(f"\nCLI Output:\n{result_cli.stdout}{result_cli.stderr}") import os os.remove('bad_example.rst')
rstcheck --version
Debug
Known issues
breakingVersion 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.
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`).
affects: >=6.0.0
gotchaWhen 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.
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.
affects: All versions
gotcharstcheck'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.
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.
affects: All versions
gotcharstcheck 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).
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.
affects: All versions
Upgrade
Version history
6.3.0latest on PyPI · released Jul 28, 2026
Audit
Dependencies
sphinxoptionalRequired for Sphinx-specific RST checks and directives.
tomlioptionalRequired for parsing TOML-formatted configuration files (e.g., pyproject.toml).
Agent activity
13 hits · last 30 days
node
10
OpenAI (training)
1
Resources
rstcheck — pip install rstcheck · libregistry