rstcheck

General
CI
PyPI
Github

Checks syntax of reStructuredText and code blocks nested within it.

See the full documentation at read-the-docs

Contents

• Installation
  • Pre-commit Hook with Extras
• Supported languages in code blocks
• Examples

Installation

From pip

$ pip install rstcheck

To use pyproject.toml for configuration:

$ pip install rstcheck[toml]

To add sphinx support:

$ pip install rstcheck[sphinx]

Pre-commit Hook with Extras

To use rstcheck in a Git pre-commit hook with optional features:

1. Install pre-commit:

   pip install pre-commit
   

2. Add to .pre-commit-config.yaml:

   - repo: https://github.com/rstcheck/rstcheck
     rev: main # should be replaced with the current verison
     hooks:
       - id: rstcheck
         additional_dependencies: ['rstcheck[sphinx,toml]']
   

3. Run pre-commit install to activate.

Supported languages in code blocks

• Bash
• Doctest
• C (C99)
• C++ (C++11)
• JSON
• XML
• Python
• reStructuredText

Examples

With bad Python syntax:

====
Test
====

.. code:: python

    print(

$ rstcheck bad_python.rst
bad_python.rst:7: (ERROR/3) (python) unexpected EOF while parsing

With bad C++ syntax:

====
Test
====

.. code:: cpp

    int main()
    {
        return x;
    }

$ rstcheck bad_cpp.rst
bad_cpp.rst:9: (ERROR/3) (cpp) error: 'x' was not declared in this scope

With bad syntax in the reStructuredText document itself:

====
Test
===

$ rstcheck bad_rst.rst
bad_rst.rst:1: (SEVERE/4) Title overline & underline mismatch.