rstcheck
rstcheck is a comprehensive reStructuredText checker that validates RST syntax while also checking the validity of code blocks in various programming languages. It goes beyond basic RST syntax to ensure code examples and embedded content are also valid.
Key Features:
- Multi-language code validation for Python, C, C++, JSON, XML, and other embedded code blocks
- RST syntax validation ensuring proper reStructuredText document structure
- Configuration file support via
.rstcheck.cfgfor project-specific settings - Sphinx integration supporting Sphinx-specific directives and extensions
- Detailed error reporting with precise error locations and descriptions
- Ignore pattern support for excluding specific files or error types
- Custom error handling allowing for project-specific validation rules
- Code block syntax checking validating embedded programming language syntax
- Recursive directory scanning for bulk validation of documentation trees
- Extensible architecture supporting custom validation rules and directives
- Performance optimized for handling large documentation projects efficiently
rstcheck documentation
- Version in MegaLinter: 6.2.5
- Visit Official Web Site
- See How to configure rstcheck rules
- See How to disable rstcheck rules in files
Configuration in MegaLinter
- Enable rstcheck by adding
RST_RSTCHECKin ENABLE_LINTERS variable - Disable rstcheck by adding
RST_RSTCHECKin DISABLE_LINTERS variable
| Variable | Description | Default value |
|---|---|---|
| RST_RSTCHECK_ARGUMENTS | User custom arguments to add in linter CLI call Ex: -s --foo "bar" |
|
| RST_RSTCHECK_COMMAND_REMOVE_ARGUMENTS | User custom arguments to remove from command line before calling the linter Ex: -s --foo "bar" |
|
| RST_RSTCHECK_FILTER_REGEX_INCLUDE | Custom regex including filter Ex: (src\|lib)⚠️ Not available with RST_RSTCHECK_CLI_LINT_MODE = project |
Exclude no file |
| RST_RSTCHECK_FILTER_REGEX_EXCLUDE | Custom regex excluding filter Ex: (test\|examples)⚠️ Not available with RST_RSTCHECK_CLI_LINT_MODE = project |
Exclude no file |
| RST_RSTCHECK_CLI_LINT_MODE | Override default CLI lint mode - file: Calls the linter for each file- list_of_files: Call the linter with the list of files as argument- project: Call the linter from the root of the project |
list_of_files |
| RST_RSTCHECK_FILE_EXTENSIONS | Allowed file extensions. "*" matches any extension, "" matches empty extension. Empty list excludes all filesEx: [".py", ""] |
[".rst"] |
| RST_RSTCHECK_FILE_NAMES_REGEX | File name regex filters. Regular expression list for filtering files by their base names using regex full match. Empty list includes all files Ex: ["Dockerfile(-.+)?", "Jenkinsfile"] |
Include every file |
| RST_RSTCHECK_PRE_COMMANDS | List of bash commands to run before the linter | None |
| RST_RSTCHECK_POST_COMMANDS | List of bash commands to run after the linter | None |
| RST_RSTCHECK_UNSECURED_ENV_VARIABLES | List of env variables explicitly not filtered before calling RST_RSTCHECK and its pre/post commands | None |
| RST_RSTCHECK_CONFIG_FILE | rstcheck configuration file name Use LINTER_DEFAULT to let the linter find it |
.rstcheck.cfg |
| RST_RSTCHECK_RULES_PATH | Path where to find linter configuration file | Workspace folder, then MegaLinter default rules |
| RST_RSTCHECK_DISABLE_ERRORS | Run linter but consider errors as warnings | false |
| RST_RSTCHECK_DISABLE_ERRORS_IF_LESS_THAN | Maximum number of errors allowed | 0 |
| RST_RSTCHECK_CLI_EXECUTABLE | Override CLI executable | ['rstcheck'] |
IDE Integration
Use rstcheck in your favorite IDE to catch errors before MegaLinter !
| IDE | Extension Name | Install | |
|---|---|---|---|
| Visual Studio Code | vscode-restructuredtext |  |
MegaLinter Flavors
This linter is available in the following flavors
| Flavor | Description | Embedded linters | Info | |
|---|---|---|---|---|
 |
all | Default MegaLinter Flavor | 125 |   |
| cupcake | MegaLinter for the most commonly used languages | 92 |   |
|
| python | Optimized for PYTHON based projects | 70 |   |
Behind the scenes
How are identified applicable files
- File extensions:
.rst
How the linting is performed
rstcheck is called once on the whole project directory (project CLI lint mode)
- filtering can not be done using MegaLinter configuration variables,it must be done using rstcheck configuration or ignore file (if existing)
VALIDATE_ALL_CODEBASE: falsedoesn't make rstcheck analyze only updated files
Example calls
rstcheck myfile.rst
rstcheck -c .rstcheck.cfg myfile.rst
Help content
Usage: rstcheck [OPTIONS] {files}...
CLI of rstcheck.
Enabled features: ['Sphinx']
Pass one or more RST FILES to check.
Can be files or directories if --recursive is passed too.
Pass "-" if you want to read from stdin.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --config <path> Config file to load. Can be a INI │
│ file or directory. If a directory │
│ is passed it will be searched for │
│ .rstcheck.cfg | setup.cfg. If │
│ 'NONE' is passed no config file is │
│ loaded at all. │
│ --warn-unknown-settings Log a WARNING for unknown settings │
│ in config files. Can be hidden via │
│ --log-level. │
│ --recursive -r 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. Defaults to INFO. Can be set │
│ in config file. │
│ --log-level LEVEL The log level of the application │
│ for information that is not a │
│ linting issue. Valid levels are: │
│ DEBUG | INFO | WARNING | ERROR | │
│ CRITICAL. Defaults to WARNING. │
│ [default: WARNING] │
│ --ignore-directives <str> Comma-separated-list of directives │
│ to add to the ignore list. Can be │
│ set in config file. │
│ --ignore-roles <str> Comma-separated-list of roles to │
│ add to the ignore list. Can be set │
│ in config file. │
│ --ignore-substitutions <str> Comma-separated-list of │
│ substitutions to add to the ignore │
│ list. Can be set in config file. │
│ --ignore-languages <str> 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. │
│ --version Print versions and exit. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
Installation on mega-linter Docker image
- Dockerfile commands :
# renovate: datasource=pypi depName=rstcheck
ARG PIP_RSTCHECK_VERSION=6.2.5
# renovate: datasource=pypi depName=click
ARG PIP_RSTCHECK_CLICK_VERSION=8.4.2
- PIP packages (Python):