reStructuredText and Code Block Linter

Warnings

• breaking Version 6 introduced significant breaking changes. The codebase was restructured, with the core logic moved to `rstcheck-core`. The main repository changed from `myint/rstcheck` to `rstcheck/rstcheck`. CLI options and configuration file keys were renamed, and CLI options now overwrite config file settings. Numeric `report` levels are no longer supported.
  Fix: Review the 'Migration-Guides' in the official documentation, specifically 'Version 5 to 6'. Update CLI arguments (e.g., `--report` to `--report-level`, `--ignore-language` to `--ignore-languages`), and adjust configuration file keys (e.g., `report` to `report_level`, `ignore_language` to `ignore_languages`).
• gotcha When using `rstcheck.check()` as a module, it does not load any configuration files automatically, as this could mutate docutils registries. This means that custom configurations (e.g., ignored directives, roles) will not apply unless explicitly passed.
  Fix: If using `rstcheck.check()` programmatically, ensure all necessary configurations (like `ignore_directives`, `ignore_roles`, `ignore_messages`, `report_level`) are passed directly as arguments to the `check()` function, or use the CLI for automated config file detection.
• gotcha rstcheck's configuration file detection prioritizes `.rstcheck.cfg`, then `pyproject.toml`, then `setup.cfg`. Within `pyproject.toml`, settings must be under the `[tool.rstcheck]` section. CLI options always take precedence over configuration file settings.
  Fix: Organize your configuration according to the precedence rules. For `pyproject.toml`, ensure settings are within `[tool.rstcheck]`. Be aware that CLI arguments will override any corresponding settings in config files. Use `--warn-unknown-settings` CLI flag to get warnings about unrecognized settings in config files.
• gotcha rstcheck relies on `docutils` for parsing reStructuredText. This means it inherits `docutils`'s limitations and error reporting style. Error messages are filtered at a textual level using Python regex, as `docutils` doesn't categorize errors beyond general levels (info, warning, error, severe).
  Fix: When ignoring specific errors using `--ignore-messages` or `ignore_messages` in configuration, provide precise Python regular expressions to match the desired messages. Understand that the granularity of error filtering is limited by `docutils`'s output.

Install

• pip install rstcheck Core library
• pip install rstcheck[sphinx] With Sphinx support
• pip install rstcheck[toml] With TOML configuration support

Imports

• check

  import rstcheck
  results = list(rstcheck.check('...'))

  The primary programmatic interface for linting content.

Quickstart

This quickstart demonstrates how to use `rstcheck` programmatically with the `rstcheck.check()` function to lint reStructuredText strings, both valid and invalid. It also shows how to invoke it as a command-line tool, which is its primary use case.

import rstcheck

rst_content_good = """
Example
=======

This is a valid reStructuredText document.

.. code:: python

    print('Hello, world!')
"""

rst_content_bad = """
Bad Example
===========

This document has bad RST syntax.

.. code:: python

    print('Missing quote)
"""

# Check good content
results_good = list(rstcheck.check(rst_content_good))
print(f"Good content issues: {results_good}")

# Check bad content
results_bad = list(rstcheck.check(rst_content_bad))
print(f"Bad content issues: {results_bad}")

# Alternatively, via CLI (requires saving to a file):
# Create a temporary file for CLI example
with open('bad_example.rst', 'w') as f:
    f.write(rst_content_bad)
import subprocess
result_cli = subprocess.run(['rstcheck', 'bad_example.rst'], capture_output=True, text=True)
print(f"\nCLI Output:\n{result_cli.stdout}{result_cli.stderr}")
import os
os.remove('bad_example.rst')