tessl/pypi-sphinx-lint

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

Overview

Eval results

Files

Core Checking API

Name: tessl/pypi-sphinx-lint
Author: tessl

Primary programmatic interface for checking reStructuredText and Python documentation files for style and syntax issues. These functions form the foundation of sphinx-lint's functionality.

Capabilities

Text Content Checking

Check text content directly without reading from files, allowing for integration with editors, IDEs, or other text processing tools.

def check_text(filename, text, checkers, options=None):
    """
    Check text content for linting errors.
    
    Parameters:
    - filename (str): filename for error reporting (affects which checkers run based on extension)
    - text (str): text content to check
    - checkers (set): set of checker functions to run
    - options (CheckersOptions, optional): configuration options (defaults to CheckersOptions() if None)
    
    Returns:
    list: List of LintError objects representing found issues
    """

Usage Example

from sphinxlint import check_text
from sphinxlint.checkers import all_checkers

# Check reStructuredText content
rst_content = """
Title
=====

This is :func:`function_name` without backticks.
"""

# Use all enabled checkers
enabled_checkers = {checker for checker in all_checkers.values() if checker.enabled}
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})")

File Checking

Check files directly from the filesystem, handling file reading, encoding detection, and special file type processing.

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 (defaults to CheckersOptions() if None)
    
    Returns:
    list: List of LintError objects representing found issues, or error message strings for file access issues
    """

Usage Example

from sphinxlint import check_file
from sphinxlint.checkers import all_checkers
from sphinxlint.sphinxlint import CheckersOptions

# Check a specific file
enabled_checkers = {checker for checker in all_checkers.values() if checker.enabled}
options = CheckersOptions()
options.max_line_length = 100

errors = check_file("docs/api.rst", enabled_checkers, options)

if errors:
    for error in errors:
        if isinstance(error, str):
            print(f"File error: {error}")
        else:
            print(f"{error.filename}:{error.line_no}: {error.msg} ({error.checker_name})")
else:
    print("No issues found")

Checker Selection

Both functions accept a set of checker functions. You can filter checkers based on your needs:

from sphinxlint.checkers import all_checkers

# All enabled checkers (default behavior)
enabled_checkers = {checker for checker in all_checkers.values() if checker.enabled}

# Specific checkers only
specific_checkers = {
    all_checkers['trailing-whitespace'],
    all_checkers['missing-space-after-role']
}

# All checkers (including disabled ones)
all_available_checkers = set(all_checkers.values())

# Filter by file type support
rst_checkers = {checker for checker in all_checkers.values() if '.rst' in checker.suffixes}

File Type Support

The checking functions automatically filter checkers based on file extensions:

.rst: reStructuredText files (most checkers)
.py: Python files (Python syntax checker and general formatters)
.po: Gettext PO files (converted to RST for checking)
.html: HTML files (leaked markup checker only)

Error Handling

File checking handles various error conditions gracefully:

File not found: Returns error message string
Permission denied: Returns error message string
Unicode decode errors: Returns error message string with encoding details
Empty files: Returns empty list (no errors)

The functions use UTF-8 encoding by default and will report encoding issues if files cannot be decoded.

Performance Considerations

Per-file caches are automatically cleared after each file check to prevent memory leaks
PO files are converted to RST format before checking, which adds processing overhead
Checker filtering by file extension reduces unnecessary processing

Install with Tessl CLI