rstcheck-core

1.2.2 · active · verified Sun Apr 12

rstcheck-core is the core library behind the rstcheck CLI application, used for checking the syntax of reStructuredText documents and code blocks embedded within them. It leverages docutils for parsing RST and reports found issues. The library follows semantic versioning, with bugfixes typically supported only for the current minor release. It has a regular release cadence, with updates often reflecting changes in the broader rstcheck ecosystem.

Warnings

breaking The `rstcheck` project underwent a significant architectural change with version 6.0.0, where the core logic was extracted into the `rstcheck-core` library. Direct imports or interactions with internal `rstcheck` modules from versions 5.x or earlier will break when migrating to `rstcheck-core` or `rstcheck` v6+.
Fix: Update import paths to use `rstcheck_core` where applicable. Review CLI options and configuration file keys as many were renamed or changed in `rstcheck` v6.
gotcha Windows support for `rstcheck-core` is explicitly stated as not stable. Tests can fail with incorrect positives and negatives for unknown reasons, which may lead to unreliable linting results on Windows systems.
Fix: For critical usage, consider running `rstcheck-core` within a Linux environment (e.g., WSL, Docker) or use a CI/CD pipeline running on Linux. Monitor GitHub issues for updates on Windows stability.
gotcha Configuration settings defined in files (e.g., `.rstcheck.cfg`, `pyproject.toml`, `setup.cfg`) can be completely overridden by command-line interface (CLI) options. Additionally, `rstcheck-core` searches for configuration files by traversing up the directory tree from the checked file, which might lead to unexpected configuration being applied if not carefully managed.
Fix: Be explicit with CLI options if overriding configuration is intended. If you need to debug which configuration file is being used, `rstcheck` (the CLI tool) has a `--log-level DEBUG` option that can help. Ensure your project structure and configuration file placement match the expected search behavior, or explicitly specify the config file path using `--config`.

Install

pip install rstcheck-core Install core library
pip install rstcheck-core[sphinx,toml,yaml] Install with optional extras

Imports

check
```
from rstcheck_core import check
```
The `rstcheck.check` import is for the older, monolithic `rstcheck` package. `rstcheck-core` is the separated core library, requiring direct import from `rstcheck_core`.

Quickstart

This quickstart demonstrates how to use the `check` function from `rstcheck_core` to programmatically validate reStructuredText content. It will yield a series of (line_number, message) tuples for any detected issues.

from rstcheck_core import check

rst_content = '''
Example
=======

.. code:: python
    print("Hello, rstcheck!")

.. code:: badlang
    This language does not exist.
'''

issues = list(check(rst_content))
for line, message in issues:
    print(f"Line {line}: {message}")

# Example with an actual error:
error_rst = '''
Bad RST
=======

This title underline is too short.
===
'''
issues_with_error = list(check(error_rst))
for line, message in issues_with_error:
    print(f"Line {line}: {message}")

view raw JSON →