or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

checkers.mdcli.mdconfiguration.mdcore-checking.mdindex.md
tile.json

tessl/pypi-sphinx-lint

Check for stylistic and formal issues in .rst and .py files included in the documentation

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/sphinx-lint@1.0.x

To install, run

npx @tessl/cli install tessl/pypi-sphinx-lint@1.0.0

index.mddocs/

Sphinx-Lint

A command-line tool for checking stylistic and formal issues in reStructuredText (.rst) files and Python documentation files. Based on rstlint.py from CPython, sphinx-lint provides fast linting capabilities designed to find errors that are not visible to sphinx-build, focusing on reStructuredText syntax validation, role and directive checking, and documentation style enforcement.

Package Information

  • Package Name: sphinx-lint
  • Language: Python
  • Installation: pip install sphinx-lint
  • Python Requirements: Python >= 3.8

Core Imports

import sphinxlint

For programmatic usage:

from sphinxlint import check_text, check_file

For CLI functionality:

from sphinxlint.cli import main

Basic Usage

Command Line

# Check specific files
sphinx-lint file1.rst file2.py

# Check directory recursively
sphinx-lint docs/

# Enable/disable specific checkers
sphinx-lint --disable trailing-whitespace --enable line-too-long docs/

# Run with parallel processing
sphinx-lint --jobs 4 docs/

# List available checkers
sphinx-lint --list

Programmatic Usage

from sphinxlint import check_text, check_file
from sphinxlint.checkers import all_checkers

# Check text content
enabled_checkers = set(all_checkers.values())
errors = check_text("example.rst", rst_content, enabled_checkers)

for error in errors:
    print(f"{error.filename}:{error.line_no}: {error.msg} ({error.checker_name})")

# Check file
errors = check_file("docs/example.rst", enabled_checkers)

Architecture

Sphinx-lint is organized around a modular checker system:

  • Checkers: Individual functions that detect specific style or syntax issues
  • Checker Registry: Central registry (all_checkers) containing all available checkers
  • Error Reporting: Structured error objects with filename, line number, message, and checker name
  • File Processing: Support for multiple file types (.rst, .py, .po, .html) with appropriate filtering
  • CLI Framework: Full command-line interface with parallel processing, sorting, and configuration options

The checker decorator system allows easy registration of new checkers with metadata about supported file types and default enabled state.

Capabilities

Core Checking Functions

Primary API for programmatically checking content and files for reStructuredText and Python documentation issues.

def check_text(filename, text, checkers, options=None):
    """
    Check text content for linting errors.
    
    Parameters:
    - filename (str): filename for error reporting and checker filtering
    - text (str): text content to check
    - checkers (set): set of checker functions to run
    - options (CheckersOptions, optional): configuration options
    
    Returns:
    list of LintError objects
    """

def check_file(filename, checkers, options=None):
    """
    Check a file for linting errors.
    
    Parameters:
    - filename (str): path to file to check
    - checkers (set): set of checker functions to run  
    - options (CheckersOptions, optional): configuration options
    
    Returns:
    list of LintError objects or error message strings
    """

Core Checking API

Command-Line Interface

Full-featured CLI with support for checker configuration, parallel processing, error sorting, and output formatting.

def main(argv=None):
    """
    Main CLI entry point for sphinx-lint.
    
    Parameters:
    - argv (list, optional): command-line arguments (defaults to sys.argv)
    
    Returns:
    int: exit code (0 for success, non-zero for errors)
    """

def parse_args(argv=None):
    """
    Parse command line arguments.
    
    Parameters:
    - argv (list, optional): command-line arguments
    
    Returns:
    tuple: (enabled_checkers_set, parsed_args_namespace)
    """

Command-Line Interface

Available Checkers

Built-in checkers for detecting common reStructuredText syntax issues, Python documentation problems, and general formatting issues.

def checker(*suffixes, **kwds):
    """
    Decorator to register a function as a checker.
    
    Parameters:
    - *suffixes: file extensions this checker supports
    - **kwds: checker properties (enabled, rst_only)
    
    Returns:
    decorated function with checker metadata
    """

# Global registry of all checker functions
all_checkers = {}  # dict mapping checker names to functions

Available Checkers

Configuration and Options

Configuration system for controlling checker behavior and output formatting.

class CheckersOptions:
    """Configuration options for checkers"""
    max_line_length = 80
    
    @classmethod
    def from_argparse(cls, namespace):
        """Create options from argparse namespace"""

Configuration Options

Error Handling

Sphinx-lint uses structured error reporting through the LintError class. All checking functions return lists of error objects or handle file system errors gracefully by returning error messages.

Types

@dataclass(frozen=True)
class LintError:
    """A linting error found by one of the checkers"""
    filename: str
    line_no: int  
    msg: str
    checker_name: str
    
    def __str__(self):
        """Return formatted error string"""

class CheckersOptions:
    """Configuration options for checkers"""
    max_line_length = 80
    
    @classmethod  
    def from_argparse(cls, namespace):
        """Create CheckersOptions from argparse namespace"""