Checks syntax of reStructuredText and code blocks nested within it.
Project description
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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.