rstcheck 6.0.0a2

Installation

From pip

$ pip install rstcheck

To use pyproject.toml for configuration:

$ pip install rstcheck[toml]

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

If sphinx and tomli are installed:

Usage: rstcheck [OPTIONS] FILES...

CLI of rstcheck.

Enabled features: ['Sphinx', 'Toml']

Arguments:
FILES...  RST files to check. Can be files or directories if --recursive is
            passed too.  [required]

Options:
--config PATH                Config file to load. Can be a INI or TOML file
                            or directory. If a directory is passed it will
                            be searched for .rstcheck.cfg | pyproject.toml
                            | setup.cfg.
-r, --recursive              Recursively search passed directories for RST
                            files to check.
--report-level LEVEL         The report level of the linting issues found.
                            Valid levels are: INFO | WARNING | ERROR |
                            SEVERE | NONE. Defauls to INFO. Can be set in
                            config file.
--ignore-directives TEXT     Comma-separated-list of directives to add to
                            the ignore list. Can be set in config file.
--ignore-roles TEXT          Comma-separated-list of roles to add to the
                            ignore list. Can be set in config file.
--ignore-substitutions TEXT  Comma-separated-list of substitutions to add to
                            the ignore list. Can be set in config file.
--ignore-languages TEXT      Comma-separated-list of languages for code-
                            blocks to add to the ignore list. The code in
                            ignored code-blocks will not be checked for
                            errors. Can be set in config file.
--ignore-messages REGEX      A regular expression to match linting issue
                            messages against to ignore. Can be set in
                            config file.
--install-completion         Install completion for the current shell.
--show-completion            Show completion for the current shell, to copy
                            it or customize the installation.
--help                       Show this message and exit.

Ignore specific languages

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

.. rstcheck: ignore-languages=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, setup.cfg, or pyproject.toml in the directory or ancestor directories of the file it is checking.

.rstcheck.cfg takes precedence over setup.cfg.

Settings in the config file are overwritten by CLI options.

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_level=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.

For a PEP-517/PEP-518 project, you should put the configuration settings for rstcheck inside the pyproject.toml configuration file in the project root. These should be placed in a [tool.rstcheck] section. Keep in mind backslashes need to be escaped, so to ignore the message "(Document or section may not begin with a transition\.$)" you’ll need to escape the backslash in pyproject.toml like this "(Document or section may not begin with a transition\\.$)". See the pyproject.toml file in examples/with_configuration.

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.

Sphinx

To enable Sphinx

$ pip install rstcheck[sphinx]

# or

$ pip install sphinx

With version 4.0 rstcheck added Sphinx as an optional extra where the version’s lower constraint is >=4.0 because of Sphinx’s open upper constraints on jinja2 and markupsafe, which result in import errors if not pinned below version 3 and 2 respectively. This happend in Sphinx version 4.0.

You can also add Sphinx by yourself but the installed Sphinx version must be at least 2.0.

To check that Sphinx support is enabled

$ rstcheck -h | grep 'Sphinx is enabled'

Usage in Vim

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.

Use as a pre-commit hook

Add this to your .pre-commit-config.yaml

-   repo: https://github.com/myint/rstcheck
    rev: ''  # Use the sha / tag you want to point at
    hooks:
    -   id: rstcheck

Use with Mega-Linter:

Just install Mega-Linter in your repository, rstcheck is part of the 70 linters activated out of the box.

Development

This project relies on poetry as its management tool for dependencies, building and venvs. You do not need to have poetry installed globally, but it is recommended to.

For development venv creation run

$ poetry install

# or without global `poetry`

$ python3 -m venv .venv
$ source .venv/bin/activate
$ pip install poetry

With global poetry you do not need to activate the venv. poetry will run commands inside the venv if you call them like this

$ poetry run COMMAND

# With global `poetry` or with active development venv:
$ poetry run tox

# With active development venv:
$ tox

# Without `poetry` and development venv:
$ python3 -m venv .venv
$ source .venv/bin/activate
$ pip install tox
$ tox

Known limitations / FAQ

There are inherent limitations to what rstcheck can and cannot do. The reason for this is that rstcheck itself does not parse the rst source but gives it to docutils and gets the errors back. Therefore rstcheck in the sense of rst source is more an error accumulation tool. The same goes for the source code in supported code blocks.

History