reStructuredText Linter

2.0.2 · active · verified Thu Apr 09

restructuredtext-lint is a Python library for linting reStructuredText (RST) documents to identify errors, warnings, and style issues. It leverages `docutils` for parsing and provides programmatic access to linting results, including line numbers, types, and messages. The current version is 2.0.2, and it maintains a slow but active release cadence, primarily focusing on bug fixes and compatibility with newer Python and `docutils` versions.

Warnings

breaking The import path for `lint_file` changed significantly in version 2.0.0, moving from the main `lint` module to a dedicated `file_lint` module.
Fix: Update your import statements: change `from restructuredtext_lint.lint import lint_file` to `from restructuredtext_lint.file_lint import lint_file`.
breaking Version 2.x and above of `restructuredtext-lint` are exclusively Python 3 compatible. Earlier 1.x versions supported Python 2.
Fix: Ensure your environment is running Python 3. For projects still requiring Python 2, you must pin the dependency to `restructuredtext-lint<2.0.0`.
gotcha Linting results (errors) can have different severity `type` values, including 'info', 'warning', 'error', and 'severe'. Consumers of the library must handle these distinctions if they wish to filter or prioritize issues.
Fix: When processing the list of `errors`, inspect the `error.type` attribute to filter or categorize issues according to your requirements. For example, `if error.type == 'error': ...`.
gotcha In version 2.0.0, `lint_file` briefly switched its parsing backend from `docutils` to `sphinx`. This was reverted in 2.0.1, restoring `docutils` as the backend. This might cause subtle behavioral differences or break Sphinx-specific directives if upgrading *only* to 2.0.0, then later upgrading to 2.0.1+.
Fix: If relying on `lint_file` and specific Sphinx extensions or features, be aware that 2.0.0 was the only version in the 2.x series to explicitly support a Sphinx backend; subsequent versions reverted to `docutils`. Test thoroughly when upgrading through these specific point releases.

Install

pip install restructuredtext-lint Install stable version

Imports

lint
```
from restructuredtext_lint import lint
```
lint_file
```
from restructuredtext_lint.file_lint import lint_file
```
The import path for `lint_file` changed in version 2.0.0. It was moved from the top-level `lint` module to `file_lint`.

Quickstart

This quickstart demonstrates how to use `restructuredtext-lint` to check a string for reStructuredText syntax errors and warnings. It iterates through the detected errors, printing their type, line number, and message. It also shows the general approach for linting files.

from restructuredtext_lint import lint

rst_content = '''
My Document
===========

.. This is a comment

This is a paragraph with some `broken

.. bad_directive::

An error will be reported above.
'''

errors = lint(rst_content)

if errors:
    print(f"Found {len(errors)} linting issues:")
    for error in errors:
        print(f"  [{error.type.upper()}] Line {error.line}: {error.message}")
else:
    print("No linting issues found.")

# To lint a file:
# from restructuredtext_lint.file_lint import lint_file
# errors_from_file = lint_file('path/to/your/file.rst')

view raw JSON →