rstcheck
Checks syntax of reStructuredText and code blocks nested within it.
Installation
From pip:
$ pip install rstcheck
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.
Options
usage: rstcheck [-h] [-r] [--report level] [--ignore-language language]
[--ignore-messages messages] [--ignore-directives directives]
[--ignore-substitutions substitutions] [--ignore-roles roles]
[--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
-r, --recursive run recursively over directories
--report level report system messages at or higher than level; info,
warning, error, severe, none (default: info)
--ignore-language language, --ignore language
comma-separated list of languages to ignore
--ignore-messages messages
python regex that match the messages to ignore
--ignore-directives directives
comma-separated list of directives to ignore
--ignore-substitutions substitutions
comma-separated list of substitutions to ignore
--ignore-roles roles comma-separated list of roles to ignore
--debug show messages helpful for debugging
--version show program's version number and exit
Ignore specific 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,rstIgnore specific errors
Since docutils doesn’t categorize their error messages beyond the high-level categories of: info, warning, error, and severe; we need filter them out at a textual level. This is done by passing a Python regex. As example you can pass a regex like this to ignore several errors:
(Title underline too short.*|Duplicate implicit target.*')
Configuration file
You can use the same arguments from the command line as options in the local configuration file of the project (just replace - for _). 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:
[rstcheck]
ignore_directives=one,two,three
ignore_roles=src,RFC
ignore_messages=(Document or section may not begin with a transition\.$)
report=warningbar.rst contains:
Bar
===
:src:`hello_world.py`
:RFC:`793`
.. one::
Hellorstcheck will make use of the .rstcheck.cfg:
$ rstcheck docs/foo/bar.rst
Sphinx
To enable Sphinx:
$ pip install sphinx
The installed Sphinx version must be at least 1.5.
To check that Sphinx support is enabled:
$ rstcheck -h | grep 'Sphinx is enabled'
Usage in Vim
Using with Syntastic:
let g:syntastic_rst_checkers = ['rstcheck']Using with ALE:
Just install rstcheck and make sure is on your path.
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.
Testing
To run all the tests, do:
$ make test
Unit tests are in test_rstcheck.py.
System tests are composed of example good/bad input. The test inputs are contained in the examples directory. For basic tests, adding a test should just be a matter of adding files to examples/good or examples/bad.
History
3.3.1 (2018-10-09)
Make compatible with Sphinx >= 1.8.
3.3 (2018-03-17)
Parse more options from configuration file (thanks to Santos Gallegos).
Allow ignoring specific (info/warning/error) messages via --ignore-messages (thanks to Santos Gallegos).
3.2 (2018-02-17)
Check for invalid Markdown-style links (thanks to biscuitsnake).
Allow configuration to be stored in setup.cfg (thanks to Maël Pedretti).
Add --recursive option to recursively drill down directories to check for all *.rst files.
3.1 (2017-03-08)
Add support for checking XML code blocks (thanks to Sameer Singh).
3.0.1 (2017-03-01)
Support UTF-8 byte order marks (BOM). Previously, docutils would interpret the BOM as a visible character, which would lead to false positives about underlines being too short.
3.0 (2016-12-19)
Optionally support Sphinx 1.5. Sphinx support will be enabled if Sphinx is installed.
2.0 (2015-07-27)
Support loading settings from configuration files.
1.0 (2015-03-14)
Add Sphinx support.
0.1 (2013-12-02)
Initial version.
Release files for rstcheck 3.3.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| rstcheck-3.3.1.tar.gz | 13.8 kB | Details |
Release files / rstcheck-3.3.1.tar.gz
| Download URL | rstcheck-3.3.1.tar.gz |
|---|---|
| Size | 13.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
92c4f79256a54270e0402ba16a2f92d0b3c15c8f4410cb9c57127067c215741f
|
|
BLAKE2b-256 checksum How to use checksums |
813f42c187b6e0840145a45021ceb1a2c83697b9aa41068add75d1fa6757bdca
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/1.8.1 pkginfo/1.4.1 requests/2.18.4 setuptools/32.3.1 requests-toolbelt/0.7.0 clint/0.5.1 CPython/3.6.6 Darwin/16.7.0
|
