restructuredtext-lint

What it is and what it does

restructuredtext-lint checks reStructuredText files for structural violations before they are uploaded to PyPI or deployed. It wraps docutils parsing and exposes both a Python API (lint() and lint_file() functions) and a command-line tool (rst-lint) that report errors with line numbers, severity levels, and descriptive messages. Each error includes metadata like source file, error type (INFO/WARNING/ERROR/SEVERE), and the full context where the problem occurred.

The package was created to catch reST formatting issues locally rather than discovering them after publishing. It supports prepending content via rst_prolog for testing with substitutions, filtering by error severity, and output in text or JSON format. Custom directives and roles can be registered via docutils' extension mechanism, though Sphinx-specific customizations require manual registration due to parser differences.

Use it for:

• Validate README.rst and other documentation files before pushing to PyPI or a repository
• Integrate linting into CI/CD pipelines to catch reStructuredText errors early
• Check documentation consistency in projects using Sphinx or docutils
• Programmatically lint reST content in build scripts or documentation generators
• Detect title underlines, hyperlink issues, and lexer problems that would fail on PyPI

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Lints reStructuredText documents for structural errors and returns a list of violations with line numbers, severity levels, and messages.

Yes, if you work with reStructuredText documentation or publish to PyPI. The tool solves a real problem—catching formatting errors before upload—with low install friction and no security vulnerabilities. The aging maintenance status (264 days since release) is a minor concern for a stable linter, but the unarchived repository and active last commit suggest it is not abandoned. Install if you need local validation; skip if you only use Markdown or have no reStructuredText workflow.

Install

restructuredtext-lint on PyPI

pip install restructuredtext-lint

uv add restructuredtext-lint

poetry add restructuredtext-lint

Installing restructuredtext-lint

Before you install

Low friction installation with a single runtime dependency (docutils). Package is aging (264 days since last release) but repository remains active and unarchived with a modest user base.

License in practice

Released to public domain under UNLICENSE, permitting unrestricted use, modification, and distribution with no attribution or warranty obligations.

Quickstart

pip install restructuredtext-lint

import restructuredtext_lint
errors = restructuredtext_lint.lint("Hello World\n=======\n")
print(errors[0].message if errors else "No errors")

Verify before relying

• Whether Python version support is truly unspecified or simply undocumented in the fact sheet
• Current state of Sphinx directive/role compatibility beyond the known limitations mentioned in docs

Package facts

Evidence: restructuredtext_lint-2.0.2-py3-none-any.whl

Keywords: restructuredtext, restructured text, rest, rst, lint

Tags

More Markup packages