sphinx-lint

library1.0.2pypypiunverified

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.

devops testing

pip install sphinx-lint

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · SPHINX-LINT

sphinx-lint

devopspythonv1.0.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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

sphinx-lint --version

Debug

Known issues

breakingPython 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.

affects: >=1.0.1

breakingVersion 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.

affects: 1.0.2

breakingAs 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.

affects: >=0.9.0

gotchaSphinx 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.

affects: All versions

gotchaWhen 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.

affects: <0.8.1 (for manual configuration)

Errors

Common errors & fixes

command not found: sphinx-lint

The `sphinx-lint` executable is not in your system's PATH, typically because it wasn't installed correctly or the Python environment's script directory is not included in PATH.

fix

Ensure `sphinx-lint` is installed in an environment whose script directory is in your system's PATH, or run it using `python -m sphinx_lint`.

JSONDecodeError: Expecting value: line 1 column 1 (char 0)

The `.sphinx-lint.json` configuration file contains invalid JSON syntax, preventing `sphinx-lint` from parsing it correctly.

fix

Review and correct the syntax of your `.sphinx-lint.json` file to ensure it is valid JSON.

Error: No such option: --ignore

The `sphinx-lint` command-line interface does not support direct command-line options like `--ignore` for disabling specific rules, unlike some other linters.

fix

To ignore specific rules, use the `ignore` field in your `.sphinx-lint.json` configuration file, or add `# rst-lint: noqa` comments directly in your `.rst` files.

[ERROR] The program sphinx-lint is not installed (pre-commit)

The `pre-commit` framework could not find or install the `sphinx-lint` executable for the specified hook, often due to an incorrect `repo` URL, `rev`, or an issue during `pre-commit`'s environment setup.

fix

Ensure your `.pre-commit-config.yaml` correctly specifies the `sphinx-lint` hook (e.g., `repo: https://github.com/sphinx-contrib/sphinx-lint`, `id: sphinx-lint`, and a valid `rev`). Run `pre-commit autoupdate` and `pre-commit install` to refresh the hook environment.

Upgrade

Version history

1.0.2latest on PyPI · released Nov 19, 2025

Audit

Dependencies

pythonrequiredRequires Python 3.10 or newer.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/sphinx-contrib/sphinx-lint ↗

packagehttps://pypi.org/project/sphinx-lint/ ↗

changeloghttps://github.com/sphinx-contrib/sphinx-lint/releases ↗