Configuration Options

class CheckersOptions:
    """Configuration options for checkers."""
    
    max_line_length = 80
    
    @classmethod
    def from_argparse(cls, namespace):
        """
        Create CheckersOptions from argparse namespace.
        
        Parameters:
        - namespace (argparse.Namespace): from CLI argument parsing
        
        Returns:
        CheckersOptions: instance with values from command-line arguments
        """

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

# Create custom options
options = CheckersOptions()
options.max_line_length = 120

# Use with checking functions
enabled_checkers = {checker for checker in all_checkers.values() if checker.enabled}
errors = check_file("docs/api.rst", enabled_checkers, options)

# Enable specific checkers (including disabled-by-default ones)
sphinx-lint --enable line-too-long,default-role docs/

# Disable specific checkers
sphinx-lint --disable trailing-whitespace,horizontal-tab docs/

# Complex combinations (evaluated left-to-right)
sphinx-lint --disable all --enable trailing-whitespace docs/
sphinx-lint --enable all --disable line-too-long,default-role docs/

# Set custom line length limit
sphinx-lint --max-line-length 120 docs/

# Use with line-too-long checker (disabled by default)
sphinx-lint --enable line-too-long --max-line-length 88 docs/

# Parallel processing configuration
sphinx-lint --jobs 4 docs/           # Use 4 parallel processes
sphinx-lint --jobs auto docs/        # Auto-detect CPU count (default)
sphinx-lint --jobs 1 docs/           # Force single-threaded

# Output sorting configuration
sphinx-lint --sort-by filename docs/              # Sort by filename
sphinx-lint --sort-by line docs/                  # Sort by line number
sphinx-lint --sort-by error_type docs/            # Sort by checker name
sphinx-lint --sort-by filename,line docs/         # Multiple sort criteria

# Ignore specific paths
sphinx-lint --ignore build/ docs/
sphinx-lint --ignore __pycache__ --ignore "*.tmp" docs/

# Multiple ignore patterns
sphinx-lint -i build/ -i temp/ -i "*.backup" docs/

# Verbose output (show all checked files)
sphinx-lint --verbose docs/

# List available checkers
sphinx-lint --list
sphinx-lint --list --verbose    # Include detailed descriptions

class SortField(enum.Enum):
    """Fields available for sorting error reports"""
    
    FILENAME = 0
    LINE = 1
    ERROR_TYPE = 2
    
    @staticmethod
    def as_supported_options() -> str:
        """
        Return comma-separated list of supported sort field names.
        
        Returns:
        String of lowercase field names separated by commas
        """

from sphinxlint.cli import SortField

# Get available sort options
print(f"Available sort fields: {SortField.as_supported_options()}")

# Use in programmatic sorting
sort_fields = [SortField.FILENAME, SortField.LINE]

from sphinxlint.sphinxlint import CheckersOptions

# Create with custom settings
options = CheckersOptions()
options.max_line_length = 100

# The options object is passed to all checker functions
# Individual checkers can access configuration through the options parameter

import argparse
from sphinxlint.sphinxlint import CheckersOptions

# Create argparse parser
parser = argparse.ArgumentParser()
parser.add_argument('--max-line-length', type=int, default=80)
args = parser.parse_args(['--max-line-length', '120'])

# Convert to CheckersOptions
options = CheckersOptions.from_argparse(args)
print(f"Max line length: {options.max_line_length}")  # Output: 120

lint-docs:
	sphinx-lint --max-line-length 120 --disable trailing-whitespace docs/

#!/bin/bash
# lint-docs.sh
sphinx-lint \
    --max-line-length 120 \
    --disable trailing-whitespace,horizontal-tab \
    --enable line-too-long \
    --jobs auto \
    --sort-by filename,line \
    "$@"

repos:
  - repo: https://github.com/sphinx-contrib/sphinx-lint
    rev: v1.0.0
    hooks:
      - id: sphinx-lint
        args:
          - --max-line-length=120
          - --disable=trailing-whitespace
          - --enable=line-too-long

# GitHub Actions example
- name: Lint documentation
  run: |
    pip install sphinx-lint
    sphinx-lint \
      --max-line-length 88 \
      --enable line-too-long \
      --disable trailing-whitespace \
      --jobs auto \
      --sort-by filename,line \
      docs/

// VS Code settings.json example
{
  "python.linting.enabled": true,
  "python.linting.sphinxLintEnabled": true,
  "python.linting.sphinxLintArgs": [
    "--max-line-length=120",
    "--disable=trailing-whitespace"
  ]
}