Command-Line Interface

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

from sphinxlint.cli import main
import sys

# Run sphinx-lint programmatically
exit_code = main(['sphinx-lint', '--disable', 'trailing-whitespace', 'docs/'])
sys.exit(exit_code)

def parse_args(argv=None):
    """
    Parse command line arguments and return enabled checkers and parsed arguments.
    
    Parameters:
    - argv (list, optional): list of command-line arguments (defaults to sys.argv if None)
    
    Returns:
    tuple: (enabled_checkers_set, parsed_args_namespace)
    
    Raises:
    SystemExit: on invalid arguments or unknown checker names
    """

# Check specific files or directories
sphinx-lint file1.rst file2.py docs/

# Verbose output (print all checked filenames)
sphinx-lint --verbose docs/

# Show version information
sphinx-lint --version

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

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

# Disable all checkers, then enable specific ones
sphinx-lint --disable all --enable trailing-whitespace docs/

# Enable all checkers, then disable specific ones
sphinx-lint --enable all --disable line-too-long docs/

# List available checkers
sphinx-lint --list

# List checkers with detailed descriptions
sphinx-lint --list --verbose

# Set maximum line length
sphinx-lint --max-line-length 120 docs/

# Parallel processing with specific job count
sphinx-lint --jobs 4 docs/

# Auto-detect CPU count for parallel processing (default)
sphinx-lint --jobs auto docs/

# Force single-threaded processing
sphinx-lint --jobs 1 docs/

# Ignore specific files or directories
sphinx-lint --ignore build/ --ignore temp.rst docs/

# Multiple ignore patterns
sphinx-lint --ignore build/ --ignore __pycache__ --ignore "*.tmp" docs/

# Sort errors by filename
sphinx-lint --sort-by filename docs/

# Sort by line number
sphinx-lint --sort-by line docs/

# Sort by error type (checker name)
sphinx-lint --sort-by error_type docs/

# Multiple sort criteria (applied in order)
sphinx-lint --sort-by filename,line docs/

def walk(path, ignore_list):
    """
    Wrapper around os.walk with an ignore list.
    
    It also allows giving a file, thus yielding just that file.
    
    Parameters:
    - path (str): file or directory path to walk
    - ignore_list (list): list of paths/patterns to ignore
    
    Yields:
    str: File paths suitable for checking
    """

def sort_errors(results, sorted_by):
    """
    Flattens and potentially sorts errors based on user preferences.
    
    Parameters:
    - results (iterable): iterable of error lists from checking functions
    - sorted_by (list): list of SortField enum values for sorting priority
    
    Yields:
    LintError: Individual LintError objects in sorted order
    """

def print_errors(errors):
    """
    Print errors (or a message if nothing is to be printed).
    
    Parameters:
    - errors (iterable): iterable of LintError objects
    
    Returns:
    int: Number of errors printed
    """

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"""

repos:
  - repo: https://github.com/sphinx-contrib/sphinx-lint
    rev: v1.0.0
    hooks:
      - id: sphinx-lint
        args: [--disable, trailing-whitespace]

lint-docs:
	sphinx-lint --jobs auto --sort-by filename docs/

lint-docs-strict:
	sphinx-lint --enable all --max-line-length 88 docs/

- name: Check documentation
  run: |
    pip install sphinx-lint
    sphinx-lint --jobs auto --sort-by filename,line docs/