Sphinx Lint

1.0.2 · active · verified Mon Apr 13

Sphinx Lint is a lightweight Python linter designed to check for stylistic and formal issues in `.rst` (reStructuredText) and `.py` (Python) files primarily used in Sphinx documentation. It complements other linters by focusing on Sphinx-specific field list conventions and semantic consistency checks. The current version is 1.0.2, and the library maintains an active release cadence with regular updates and improvements.

Warnings

breaking Python 3.8 and 3.9 support was officially dropped in version 1.0.1. Users on older Python versions must upgrade their environment to Python 3.10 or newer to use sphinx-lint >= 1.0.1.
Fix: Upgrade your Python environment to 3.10 or a later supported version.
breaking Version 1.0.2 introduced new linting rules for hyperlinks (flagging unnecessary underscores) and roles starting with `!~`. Existing documentation that previously passed linting might now fail due to these newly enforced stylistic and formal checks.
Fix: Review and update affected `.rst` and `.py` files to comply with the new linting rules for hyperlinks and roles.
breaking As of v0.9.0, Sphinx Lint prints error messages to `stderr` instead of `stdout`. Scripts or CI/CD pipelines that parsed `stdout` for linting failures will need to be updated to capture `stderr` instead.
Fix: Modify any scripts or automation that consume sphinx-lint's output to capture `stderr` for error reporting.
gotcha Sphinx Lint has known limitations with tables. Due to its line-by-line parsing, it may incorrectly flag roles within complex table structures as unclosed or malformed. To mitigate false positives, some rules are skipped when content is detected within a table.
Fix: Be aware of potential false positives when linting files containing complex reStructuredText tables. If encountered, consider disabling specific checks locally or accepting the limitation.
gotcha When using `sphinx-lint` with `pre-commit`, it is recommended to set `require_serial: true` for the hook to prevent potential issues with parallel execution, especially on Windows or when dealing with file locking. This became the default in v0.8.1, but custom or older configurations might need adjustment.
Fix: Ensure your `.pre-commit-config.yaml` includes `require_serial: true` for the `sphinx-lint` hook to ensure reliable execution across environments.

Install

pip install sphinx-lint Install stable version

Quickstart

Sphinx Lint is primarily used as a command-line tool or integrated with pre-commit hooks. The most common setup involves adding it to your project's `.pre-commit-config.yaml` to ensure documentation quality before commits. For direct command-line usage, simply run `sphinx-lint` with paths to files or directories.

pip install sphinx-lint pre-commit
pre-commit install

# .pre-commit-config.yaml example
# In your project's root:
# git init
# pre-commit install
# vim .pre-commit-config.yaml
# Add the following content:
#
# repos:
#   - repo: https://github.com/sphinx-contrib/sphinx-lint
#     rev: v1.0.2 # Use the latest release tag
#     hooks:
#       - id: sphinx-lint
#         types: [rst, python]

# Command line usage
sphinx-lint
# Check a specific file
sphinx-lint docs/index.rst
# Check a directory
sphinx-lint docs
# Ignore a directory
sphinx-lint -i venv
# Show help
sphinx-lint -h

view raw JSON →