sphinx-lint

What it is and what it does

Sphinx Lint is a command-line linter for reStructuredText and Python documentation files, designed to find errors that Sphinx's own build process does not catch. It evolved from CPython's rstlint.py tool and focuses on stylistic and formal issues—malformed roles, unclosed directives, and similar problems—while deliberately avoiding duplication of checks that sphinx-build already performs. The tool runs line-by-line and is intended to be fast enough for editor integration and single-file checking.

The linter can be invoked directly on files or directories, integrated into pre-commit workflows, and configured to ignore specific paths. It aims for zero false positives, though it currently skips some rules within tables due to limitations in line-by-line parsing. Runtime dependencies are minimal (polib and regex), and it supports Python 3.10 through 3.14.

Use it for:

• Catch reStructuredText syntax errors during local editing before running a full Sphinx build.
• Enforce documentation style consistency across a project via pre-commit hooks.
• Validate documentation files in CI/CD pipelines without triggering a complete Sphinx build.
• Find role and directive issues that Sphinx's build process does not report.
• Lint individual .rst files during authoring without checking the entire documentation tree.

Worth the install?

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

Sphinx Lint checks reStructuredText and Python documentation files for stylistic and formal issues that Sphinx itself may not catch, running as a command-line linter or pre-commit hook.

Yes. Sphinx Lint is actively maintained, has no security vulnerabilities, low install friction, and a permissive license. It fills a genuine gap—catching documentation errors Sphinx misses—and is designed for both local and CI use. The line-by-line limitation in tables is a known constraint, not a hidden gotcha. Suitable for any project using reStructuredText documentation.

Install

sphinx-lint on PyPI

pip install sphinx-lint

uv add sphinx-lint

poetry add sphinx-lint

Installing sphinx-lint

Before you install

Low friction: pure Python wheel with only two runtime dependencies (polib and regex). Actively maintained with recent releases; last commit 2026-07-06 and production-stable status.

License in practice

Licensed under PSF-2.0 (Python Software Foundation License Version 2), a permissive license derived from its origin in CPython's documentation tools—no restrictions on use or distribution.

Quickstart

pip install sphinx-lint
sphinx-lint file.rst
sphinx-lint docs/

Requires Python 3.10 or later; does not work with reStructuredText tables due to line-by-line processing.

Verify before relying

• Whether false positives have been eliminated in practice or remain common in real documentation projects.
• Performance characteristics on large documentation trees or whether editor integration is truly comfortable at scale.
• Coverage of all Sphinx-invisible errors or whether some categories remain undetected.

Package facts

Evidence: sphinx_lint-1.0.2-py3-none-any.whl

Tags

More Sphinx packages