{"id":5494,"library":"sphinx-lint","title":"Sphinx Lint","description":"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.","status":"active","version":"1.0.2","language":"en","source_language":"en","source_url":"https://github.com/sphinx-contrib/sphinx-lint","tags":["linting","sphinx","documentation","rst","reStructuredText","pre-commit"],"install":[{"cmd":"pip install sphinx-lint","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires Python 3.10 or newer.","package":"python","optional":false}],"imports":[],"quickstart":{"code":"pip install sphinx-lint pre-commit\npre-commit install\n\n# .pre-commit-config.yaml example\n# In your project's root:\n# git init\n# pre-commit install\n# vim .pre-commit-config.yaml\n# Add the following content:\n#\n# repos:\n#   - repo: https://github.com/sphinx-contrib/sphinx-lint\n#     rev: v1.0.2 # Use the latest release tag\n#     hooks:\n#       - id: sphinx-lint\n#         types: [rst, python]\n\n# Command line usage\nsphinx-lint\n# Check a specific file\nsphinx-lint docs/index.rst\n# Check a directory\nsphinx-lint docs\n# Ignore a directory\nsphinx-lint -i venv\n# Show help\nsphinx-lint -h","lang":"bash","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or a later supported version.","message":"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.","severity":"breaking","affected_versions":">=1.0.1"},{"fix":"Review and update affected `.rst` and `.py` files to comply with the new linting rules for hyperlinks and roles.","message":"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.","severity":"breaking","affected_versions":"1.0.2"},{"fix":"Modify any scripts or automation that consume sphinx-lint's output to capture `stderr` for error reporting.","message":"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.","severity":"breaking","affected_versions":">=0.9.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your `.pre-commit-config.yaml` includes `require_serial: true` for the `sphinx-lint` hook to ensure reliable execution across environments.","message":"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.","severity":"gotcha","affected_versions":"<0.8.1 (for manual configuration)"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}