rstcheck

Checks syntax of reStructuredText and code blocks nested within it.

Installation

From pip:

$ pip install --upgrade rstcheck

Supported languages in code blocks

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

Examples

With bad Python syntax:

====
Test
====

.. code-block:: python

    print(

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

With bad C++ syntax:

====
Test
====

.. code-block:: 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.

Options

usage: rstcheck [-h] [--report level] [--ignore language] [--debug]
                [--version]
                files [files ...]

Checks code blocks in reStructuredText.

positional arguments:
  files              files to check

optional arguments:
  -h, --help         show this help message and exit
  --report level     report system messages at or higher than level; info, 1,
                     warning, 2, error, 3, severe, 4, none, 5 (default: info)
  --ignore language  comma-separated list of languages to ignore
  --debug            show output helpful for debugging
  --version          show program's version number and exit

Ignore languages

You can ignore checking of nested code blocks by language. Either use the command-line option --ignore or put a comment in the document:

.. rstcheck: ignore-language=cpp,python,rst

Configuration

If your project has custom roles and directives, you can specify them in the local configuration of the project. rstcheck looks for a file .rstcheck.cfg in the directory or ancestor directory of the file it is checking.

For example, consider a project with the following directory structure:

docs
├── foo
│   └── bar.rst
├── index.rst
└── .rstcheck.cfg

.rstcheck.cfg contains:

[roles]
ignore=src,RFC

[directives]
ignore=one,two,three

bar.rst contains:

Bar
===

:src:`hello_world.py`
:RFC:`793`

.. one::

   Hello

rstcheck will make use of the .rstcheck.cfg:

$ rstcheck docs/foo/bar.rst

Usage in Vim

To check reStructuredText in Vim using Syntastic:

let g:syntastic_rst_checkers = ['rstcheck']

Use as a module

rstcheck.check() yields a series of tuples. The first value of each tuple is the line number (not the line index). The second value is the error message.

>>> import rstcheck
>>> list(rstcheck.check('Example\n==='))
[(2, '(INFO/1) Possible title underline, too short for the title.')]

Note that this does not load any configuration as that would mutate the docutils registries.

Metadata

Release files for rstcheck 1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rstcheck 1.2
File	Size	Uploaded
rstcheck-1.2.tar.gz	9.3 kB	Apr 11, 2015	Details

Release files / rstcheck-1.2.tar.gz

Download URL	rstcheck-1.2.tar.gz
Size	9.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`e90d6b408345bfe150bf4d5d80b5192b162ff2a19fff6aedde8efd057d756592`
BLAKE2b-256 checksum How to use checksums	`808bae93f311205570efe48e185b56a66a2ca298e4836592df7a164d28444b23`
Upload date	Apr 11, 2015
Uploaded using Trusted Publishing? What is trusted publishing?	No