0
# Command-Line Interface
1

2
Full-featured command-line interface for sphinx-lint with support for checker configuration, parallel processing, error sorting, and flexible output formatting.
3

4
## Capabilities
5

6
### Main CLI Entry Point
7

8
Primary command-line entry point that handles argument parsing, checker selection, file processing, and result reporting.
9

10
```python { .api }
11
def main(argv=None):
12
    """
13
    Main CLI entry point for sphinx-lint.
14
    
15
    Parameters:
16
    - argv (list, optional): list of command-line arguments (defaults to sys.argv if None)
17
    
18
    Returns:
19
    int: Exit code (0 for success, non-zero for errors found or execution problems)
20
    """
21
```
22

23
#### Usage Example
24

25
```python
26
from sphinxlint.cli import main
27
import sys
28

29
# Run sphinx-lint programmatically
30
exit_code = main(['sphinx-lint', '--disable', 'trailing-whitespace', 'docs/'])
31
sys.exit(exit_code)
32
```
33

34
### Argument Parsing
35

36
Parse and validate command-line arguments, handle checker enabling/disabling, and configure processing options.
37

38
```python { .api }
39
def parse_args(argv=None):
40
    """
41
    Parse command line arguments and return enabled checkers and parsed arguments.
42
    
43
    Parameters:
44
    - argv (list, optional): list of command-line arguments (defaults to sys.argv if None)
45
    
46
    Returns:
47
    tuple: (enabled_checkers_set, parsed_args_namespace)
48
    
49
    Raises:
50
    SystemExit: on invalid arguments or unknown checker names
51
    """
52
```
53

54
## Command-Line Options
55

56
### Basic Options
57

58
```bash
59
# Check specific files or directories
60
sphinx-lint file1.rst file2.py docs/
61

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

65
# Show version information
66
sphinx-lint --version
67
```
68

69
### Checker Control
70

71
```bash
72
# Disable specific checkers
73
sphinx-lint --disable trailing-whitespace,horizontal-tab docs/
74

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

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

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

84
# List available checkers
85
sphinx-lint --list
86

87
# List checkers with detailed descriptions
88
sphinx-lint --list --verbose
89
```
90

91
### Processing Options
92

93
```bash
94
# Set maximum line length
95
sphinx-lint --max-line-length 120 docs/
96

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

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

103
# Force single-threaded processing
104
sphinx-lint --jobs 1 docs/
105
```
106

107
### File Filtering
108

109
```bash
110
# Ignore specific files or directories
111
sphinx-lint --ignore build/ --ignore temp.rst docs/
112

113
# Multiple ignore patterns
114
sphinx-lint --ignore build/ --ignore __pycache__ --ignore "*.tmp" docs/
115
```
116

117
### Output Formatting
118

119
```bash
120
# Sort errors by filename
121
sphinx-lint --sort-by filename docs/
122

123
# Sort by line number
124
sphinx-lint --sort-by line docs/
125

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

129
# Multiple sort criteria (applied in order)
130
sphinx-lint --sort-by filename,line docs/
131
```
132

133
## File Walking and Processing
134

135
### Path Walking
136

137
Walk filesystem paths with ignore list support, handling both files and directories.
138

139
```python { .api }
140
def walk(path, ignore_list):
141
    """
142
    Wrapper around os.walk with an ignore list.
143
    
144
    It also allows giving a file, thus yielding just that file.
145
    
146
    Parameters:
147
    - path (str): file or directory path to walk
148
    - ignore_list (list): list of paths/patterns to ignore
149
    
150
    Yields:
151
    str: File paths suitable for checking
152
    """
153
```
154

155
### Error Sorting
156

157
Sort and organize error results based on user preferences.
158

159
```python { .api }
160
def sort_errors(results, sorted_by):
161
    """
162
    Flattens and potentially sorts errors based on user preferences.
163
    
164
    Parameters:
165
    - results (iterable): iterable of error lists from checking functions
166
    - sorted_by (list): list of SortField enum values for sorting priority
167
    
168
    Yields:
169
    LintError: Individual LintError objects in sorted order
170
    """
171
```
172

173
### Error Reporting
174

175
Print errors to stderr with count reporting.
176

177
```python { .api }
178
def print_errors(errors):
179
    """
180
    Print errors (or a message if nothing is to be printed).
181
    
182
    Parameters:
183
    - errors (iterable): iterable of LintError objects
184
    
185
    Returns:
186
    int: Number of errors printed
187
    """
188
```
189

190
## Configuration Classes
191

192
### Sort Field Enumeration
193

194
Available fields for sorting error output.
195

196
```python { .api }
197
class SortField(enum.Enum):
198
    """Fields available for sorting error reports"""
199
    FILENAME = 0
200
    LINE = 1
201
    ERROR_TYPE = 2
202
    
203
    @staticmethod
204
    def as_supported_options() -> str:
205
        """Return comma-separated list of supported sort field names"""
206
```
207

208
## Parallel Processing
209

210
The CLI automatically determines optimal parallel processing based on file count and job settings:
211

212
- **Single-threaded**: Used when `--jobs 1` specified or fewer than 8 files
213
- **Multi-threaded**: Uses `multiprocessing.Pool` for larger file sets
214
- **CPU detection**: `--jobs auto` (default) uses `os.cpu_count()` to determine optimal job count
215

216
## Integration Examples
217

218
### Pre-commit Hook
219

220
```yaml
221
repos:
222
  - repo: https://github.com/sphinx-contrib/sphinx-lint
223
    rev: v1.0.0
224
    hooks:
225
      - id: sphinx-lint
226
        args: [--disable, trailing-whitespace]
227
```
228

229
### Make Target
230

231
```makefile
232
lint-docs:
233
	sphinx-lint --jobs auto --sort-by filename docs/
234

235
lint-docs-strict:
236
	sphinx-lint --enable all --max-line-length 88 docs/
237
```
238

239
### CI Integration
240

241
```yaml
242
- name: Check documentation
243
  run: |
244
    pip install sphinx-lint
245
    sphinx-lint --jobs auto --sort-by filename,line docs/
246
```