0
# Core Checking API
1

2
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.
3

4
## Capabilities
5

6
### Text Content Checking
7

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

10
```python { .api }
11
def check_text(filename, text, checkers, options=None):
12
    """
13
    Check text content for linting errors.
14
    
15
    Parameters:
16
    - filename (str): filename for error reporting (affects which checkers run based on extension)
17
    - text (str): text content to check
18
    - checkers (set): set of checker functions to run
19
    - options (CheckersOptions, optional): configuration options (defaults to CheckersOptions() if None)
20
    
21
    Returns:
22
    list: List of LintError objects representing found issues
23
    """
24
```
25

26
#### Usage Example
27

28
```python
29
from sphinxlint import check_text
30
from sphinxlint.checkers import all_checkers
31

32
# Check reStructuredText content
33
rst_content = """
34
Title
35
=====
36

37
This is :func:`function_name` without backticks.
38
"""
39

40
# Use all enabled checkers
41
enabled_checkers = {checker for checker in all_checkers.values() if checker.enabled}
42
errors = check_text("example.rst", rst_content, enabled_checkers)
43

44
for error in errors:
45
    print(f"{error.filename}:{error.line_no}: {error.msg} ({error.checker_name})")
46
```
47

48
### File Checking
49

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

52
```python { .api }
53
def check_file(filename, checkers, options=None):
54
    """
55
    Check a file for linting errors.
56
    
57
    Parameters:
58
    - filename (str): path to file to check
59
    - checkers (set): set of checker functions to run
60
    - options (CheckersOptions, optional): configuration options (defaults to CheckersOptions() if None)
61
    
62
    Returns:
63
    list: List of LintError objects representing found issues, or error message strings for file access issues
64
    """
65
```
66

67
#### Usage Example
68

69
```python
70
from sphinxlint import check_file
71
from sphinxlint.checkers import all_checkers
72
from sphinxlint.sphinxlint import CheckersOptions
73

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

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

81
if errors:
82
    for error in errors:
83
        if isinstance(error, str):
84
            print(f"File error: {error}")
85
        else:
86
            print(f"{error.filename}:{error.line_no}: {error.msg} ({error.checker_name})")
87
else:
88
    print("No issues found")
89
```
90

91
### Checker Selection
92

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

95
```python
96
from sphinxlint.checkers import all_checkers
97

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

101
# Specific checkers only
102
specific_checkers = {
103
    all_checkers['trailing-whitespace'],
104
    all_checkers['missing-space-after-role']
105
}
106

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

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

114
## File Type Support
115

116
The checking functions automatically filter checkers based on file extensions:
117

118
- **`.rst`**: reStructuredText files (most checkers)
119
- **`.py`**: Python files (Python syntax checker and general formatters)
120
- **`.po`**: Gettext PO files (converted to RST for checking)
121
- **`.html`**: HTML files (leaked markup checker only)
122

123
## Error Handling
124

125
File checking handles various error conditions gracefully:
126

127
- **File not found**: Returns error message string
128
- **Permission denied**: Returns error message string
129
- **Unicode decode errors**: Returns error message string with encoding details
130
- **Empty files**: Returns empty list (no errors)
131

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

134
## Performance Considerations
135

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