The standard for syntax checking.
rstcheck is a command-line tool that checks RST files for syntax errors and structural issues. It integrates with docutils and can validate:
Usage:
rstcheck my_document.rst
Pro tip: Integrate rstcheck into your pre-commit Git hooks to block commits with broken RST. rst tools
If Docutils is the engine, Sphinx is the luxury car built around it. Sphinx is the most widely used tool for RST and is the de facto standard for documenting Python projects.
Here is a professional workflow that combines the best RST tools: The standard for syntax checking
At its core, "RST tools" refers to the suite of software, editors, converters, and validators that help you write, parse, and transform ReStructuredText into beautiful HTML, PDF, or LaTeX. These tools fall into four main categories:
At the heart of every RST workflow lies Docutils (Documentation Utilities). Developed by the Python community (originally led by David Goodger), Docutils is the reference implementation that parses RST and transforms it into various output formats. Usage: rstcheck my_document
Key Components:
Why Docutils matters: It enforces RST’s strict indentation rules and role/directive syntax, ensuring that valid RST is semantically unambiguous. Most other tools wrap or build upon Docutils.
Nothing is more frustrating than a documentation build failing because of a syntax error you can't see. Enter doc8.
Doc8 is a linter specifically designed for RST (and other documentation source files). It checks your files for common errors and style violations before you even run a build.