Skip to content
Checks syntax of reStructuredText and code blocks nested within it
Python Shell Makefile
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Add --config option (#57) Apr 1, 2019
.gitignore Ignore Jul 24, 2016
.travis.yml Remove obsolete version from Travis CI Aug 24, 2019
AUTHORS.rst Add @stsewd Feb 19, 2018
LICENSE Increment date Apr 2, 2017
MANIFEST.in Publish tests (cont.) (#55) Mar 16, 2019
Makefile
README.rst Add --config option (#57) Apr 1, 2019
rstcheck.py Add --config option (#57) Apr 1, 2019
setup.py Document Python 3.6 support Jan 29, 2017
test.bash Add --config option (#57) Apr 1, 2019
test_rstcheck.py Added support for XML (#25) Mar 4, 2017

README.rst

rstcheck

Build status

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] [--config CONFIG] [-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. Sphinx is enabled.

positional arguments:
  files                 files to check

optional arguments:
  -h, --help            show this help message and exit
  --config CONFIG       location of config file
  -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,rst

Ignore 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 or setup.cfg in the directory or ancestor directories of the file it is checking.

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

foo
├── docs
│   └── 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=warning

bar.rst contains:

Bar
===

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

.. one::

   Hello

rstcheck will make use of the .rstcheck.cfg:

$ rstcheck foo/docs/bar.rst

For a Python project, you should put the configuration settings for rstcheck inside the general setup.cfg distutils configuration file, in the project root.

You can override the location of the config file with the --config argument:

$ rstcheck --config $HOME/.rstcheck.ini foo/docs/bar.rst

will use the file .rstcheck.ini in your home directory. If the argument to --config is a directory, rstcheck will search that directory and any any of its ancestors for a file .rstcheck.cfg or setup.cfg:

$ rstcheck --config foo /tmp/bar.rst

would use the project configuration in ./foo/.rstcheck.cfg to check the unrelated file /tmp/bar.rst. Calling rstcheck with the --debug option will show the location of the config file that is being used, if any.

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

(next version)

  • Add --config option to change the location of the config file.

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.
You can’t perform that action at this time.