sphinxlinter

A lightweight Python linter for Sphinx-style docstrings.
It validates structure, field consistency, and alignment between documentation and code.

Overview

Sphinx-style docstrings are widely used across Python projects, but existing tools such as pydocstyle, pydoclint, and ruff focus primarily on general docstring formatting, PEP257 compliance, and style enforcement.

It is designed to complement, not overlap with, these tools.
It targets Sphinx-specific field list conventions and performs semantic consistency checks that go beyond what other linters cover.

Specifically, it focuses on:

• 🧩 Enforces Sphinx-style field list formatting
• 🛠️ Ensures consistency between docstrings, signatures, and implementation
• 📐 Validates section order, duplication, and syntax of documented types and errors
• 📊 Generates concise, CI-friendly reports
• ⚙️ Provides a minimalist CLI for easy workflow integration
• 🐍 Uses only the Python standard library for full compatibility
• 🧼 Promotes clean, maintainable documentation

📦 Installation

Requires Python ≥ 3.9, but Python ≥ 3.11 is recommended to allow loading configuration files with tomlib from the standard library.

To install via pip, run:

pip install sphinx-linter

⚡ Quick Start

CLI Tool

After installation via pip, you can run the sphinxlinter command directly from your terminal.

Run on the current directory:

• Run in the current directory: sphinxlinter .
• Or use the short alias: spxl .

Run on specific files or directories:

spxl path/to/file.py path/to/package/

Standalone Script

Alternatively, you can download the standalone script by clicking the following link and run it with Python:

python sphinxlinter.py path/to/source/

Command Line Usage

Setting Configuration

Configuration is done via pyproject.toml. The configuration section is [tool.sphinx-linter].

Configuration File Location

The linter uses --config to specify a configuration file (pyproject.toml). If this option is not provided, it searches for a configuration file starting at the common ancestor of all specified files/directories, moving upward until it finds one or reaches the filesystem root. If no configuration file is found, the linter runs with its default settings.

Example configuration:

[tool.sphinx-linter]
# Enable all rules, alternatively specify individual rule codes
enable = ["ALL"]
# Disable specific rules, taking precedence over enable
disable = ["DOC003", "DOC101"]
# Ignore specific directories from linting
ignore = ["venv", ".cache"]

Output Format

When violations are found, the tool outputs lines in the following format:

path/to/file.py:LINE-NUMBER: [CODE] Description of the violation.

Categories:

• DOC0xx: Structure and formatting issues
• DOC1xx: Parameter issues
• DOC2xx: Return issues
• DOC3xx: Raises issues
• DOC4xx: Variable issues

Violation Codes

DOC0xx — Structure

DOC1xx — Parameters

DOC2xx — Returns

DOC3xx — Raises

DOC4xx — Variables

How It Works

The tool statically analyzes Python source code using the built-in AST module:

1. Parses FunctionDef, AsyncFunctionDef, ClassDef, and Module nodes.
2. Extracts Sphinx-style docstring fields.
3. Validates structure, syntax, and consistency with annotations.

The tool prints findings to stdout and never modifies source files.

CI Integration:
Treat any output as a failure signal in your build pipeline.

🛠️ Development

To contribute to the project, you can run the following commands for testing and documentation:

First, ensure you have the latest version of pip:

python -m pip install --upgrade pip

Running Tests

pip install --group=test --upgrade # Install test dependencies, skip if already installed
python -m pytest tests/ # Run all tests
python -m pytest tests/ --cov # Run tests with coverage

Running Linter

pip install --group=lint --upgrade  # Install lint dependencies, skip if already installed
ruff check . # Run linter

🗒️ License

This project is licensed under the MIT license._