0
# Sphinx-Lint
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: sphinx-lint
7
- **Language**: Python
8
- **Installation**: `pip install sphinx-lint`
9
- **Python Requirements**: Python >= 3.8
10
11
## Core Imports
12
13
```python
14
import sphinxlint
15
```
16
17
For programmatic usage:
18
19
```python
20
from sphinxlint import check_text, check_file
21
```
22
23
For CLI functionality:
24
25
```python
26
from sphinxlint.cli import main
27
```
28
29
## Basic Usage
30
31
### Command Line
32
33
```bash
34
# Check specific files
35
sphinx-lint file1.rst file2.py
36
37
# Check directory recursively
38
sphinx-lint docs/
39
40
# Enable/disable specific checkers
41
sphinx-lint --disable trailing-whitespace --enable line-too-long docs/
42
43
# Run with parallel processing
44
sphinx-lint --jobs 4 docs/
45
46
# List available checkers
47
sphinx-lint --list
48
```
49
50
### Programmatic Usage
51
52
```python
53
from sphinxlint import check_text, check_file
54
from sphinxlint.checkers import all_checkers
55
56
# Check text content
57
enabled_checkers = set(all_checkers.values())
58
errors = check_text("example.rst", rst_content, enabled_checkers)
59
60
for error in errors:
61
print(f"{error.filename}:{error.line_no}: {error.msg} ({error.checker_name})")
62
63
# Check file
64
errors = check_file("docs/example.rst", enabled_checkers)
65
```
66
67
## Architecture
68
69
Sphinx-lint is organized around a modular checker system:
70
71
- **Checkers**: Individual functions that detect specific style or syntax issues
72
- **Checker Registry**: Central registry (`all_checkers`) containing all available checkers
73
- **Error Reporting**: Structured error objects with filename, line number, message, and checker name
74
- **File Processing**: Support for multiple file types (.rst, .py, .po, .html) with appropriate filtering
75
- **CLI Framework**: Full command-line interface with parallel processing, sorting, and configuration options
76
77
The checker decorator system allows easy registration of new checkers with metadata about supported file types and default enabled state.
78
79
## Capabilities
80
81
### Core Checking Functions
82
83
Primary API for programmatically checking content and files for reStructuredText and Python documentation issues.
84
85
```python { .api }
86
def check_text(filename, text, checkers, options=None):
87
"""
88
Check text content for linting errors.
89
90
Parameters:
91
- filename (str): filename for error reporting and checker filtering
92
- text (str): text content to check
93
- checkers (set): set of checker functions to run
94
- options (CheckersOptions, optional): configuration options
95
96
Returns:
97
list of LintError objects
98
"""
99
100
def check_file(filename, checkers, options=None):
101
"""
102
Check a file for linting errors.
103
104
Parameters:
105
- filename (str): path to file to check
106
- checkers (set): set of checker functions to run
107
- options (CheckersOptions, optional): configuration options
108
109
Returns:
110
list of LintError objects or error message strings
111
"""
112
```
113
114
[Core Checking API](./core-checking.md)
115
116
### Command-Line Interface
117
118
Full-featured CLI with support for checker configuration, parallel processing, error sorting, and output formatting.
119
120
```python { .api }
121
def main(argv=None):
122
"""
123
Main CLI entry point for sphinx-lint.
124
125
Parameters:
126
- argv (list, optional): command-line arguments (defaults to sys.argv)
127
128
Returns:
129
int: exit code (0 for success, non-zero for errors)
130
"""
131
132
def parse_args(argv=None):
133
"""
134
Parse command line arguments.
135
136
Parameters:
137
- argv (list, optional): command-line arguments
138
139
Returns:
140
tuple: (enabled_checkers_set, parsed_args_namespace)
141
"""
142
```
143
144
[Command-Line Interface](./cli.md)
145
146
### Available Checkers
147
148
Built-in checkers for detecting common reStructuredText syntax issues, Python documentation problems, and general formatting issues.
149
150
```python { .api }
151
def checker(*suffixes, **kwds):
152
"""
153
Decorator to register a function as a checker.
154
155
Parameters:
156
- *suffixes: file extensions this checker supports
157
- **kwds: checker properties (enabled, rst_only)
158
159
Returns:
160
decorated function with checker metadata
161
"""
162
163
# Global registry of all checker functions
164
all_checkers = {} # dict mapping checker names to functions
165
```
166
167
[Available Checkers](./checkers.md)
168
169
### Configuration and Options
170
171
Configuration system for controlling checker behavior and output formatting.
172
173
```python { .api }
174
class CheckersOptions:
175
"""Configuration options for checkers"""
176
max_line_length = 80
177
178
@classmethod
179
def from_argparse(cls, namespace):
180
"""Create options from argparse namespace"""
181
```
182
183
[Configuration Options](./configuration.md)
184
185
## Error Handling
186
187
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.
188
189
## Types
190
191
```python { .api }
192
@dataclass(frozen=True)
193
class LintError:
194
"""A linting error found by one of the checkers"""
195
filename: str
196
line_no: int
197
msg: str
198
checker_name: str
199
200
def __str__(self):
201
"""Return formatted error string"""
202
203
class CheckersOptions:
204
"""Configuration options for checkers"""
205
max_line_length = 80
206
207
@classmethod
208
def from_argparse(cls, namespace):
209
"""Create CheckersOptions from argparse namespace"""
210
```