0
# Configuration Options
1

2
Configuration system for controlling checker behavior, output formatting, and processing options in sphinx-lint.
3

4
## Capabilities
5

6
### Checker Options Configuration
7

8
Main configuration class for controlling checker behavior and validation thresholds.
9

10
```python { .api }
11
class CheckersOptions:
12
    """Configuration options for checkers."""
13
    
14
    max_line_length = 80
15
    
16
    @classmethod
17
    def from_argparse(cls, namespace):
18
        """
19
        Create CheckersOptions from argparse namespace.
20
        
21
        Parameters:
22
        - namespace (argparse.Namespace): from CLI argument parsing
23
        
24
        Returns:
25
        CheckersOptions: instance with values from command-line arguments
26
        """
27
```
28

29
#### Usage Example
30

31
```python
32
from sphinxlint.sphinxlint import CheckersOptions
33
from sphinxlint import check_file
34
from sphinxlint.checkers import all_checkers
35

36
# Create custom options
37
options = CheckersOptions()
38
options.max_line_length = 120
39

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

45
### Command-Line Configuration
46

47
The CLI system provides extensive configuration options through command-line arguments.
48

49
#### Checker Selection
50

51
```bash
52
# Enable specific checkers (including disabled-by-default ones)
53
sphinx-lint --enable line-too-long,default-role docs/
54

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

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

63
#### Line Length Configuration
64

65
```bash
66
# Set custom line length limit
67
sphinx-lint --max-line-length 120 docs/
68

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

73
#### Processing Configuration
74

75
```bash
76
# Parallel processing configuration
77
sphinx-lint --jobs 4 docs/           # Use 4 parallel processes
78
sphinx-lint --jobs auto docs/        # Auto-detect CPU count (default)
79
sphinx-lint --jobs 1 docs/           # Force single-threaded
80

81
# Output sorting configuration
82
sphinx-lint --sort-by filename docs/              # Sort by filename
83
sphinx-lint --sort-by line docs/                  # Sort by line number
84
sphinx-lint --sort-by error_type docs/            # Sort by checker name
85
sphinx-lint --sort-by filename,line docs/         # Multiple sort criteria
86
```
87

88
#### File Filtering Configuration
89

90
```bash
91
# Ignore specific paths
92
sphinx-lint --ignore build/ docs/
93
sphinx-lint --ignore __pycache__ --ignore "*.tmp" docs/
94

95
# Multiple ignore patterns
96
sphinx-lint -i build/ -i temp/ -i "*.backup" docs/
97
```
98

99
#### Verbosity Configuration
100

101
```bash
102
# Verbose output (show all checked files)
103
sphinx-lint --verbose docs/
104

105
# List available checkers
106
sphinx-lint --list
107
sphinx-lint --list --verbose    # Include detailed descriptions
108
```
109

110
## Configuration Classes and Enums
111

112
### Sort Field Configuration
113

114
Enumeration of available fields for error sorting.
115

116
```python { .api }
117
class SortField(enum.Enum):
118
    """Fields available for sorting error reports"""
119
    
120
    FILENAME = 0
121
    LINE = 1
122
    ERROR_TYPE = 2
123
    
124
    @staticmethod
125
    def as_supported_options() -> str:
126
        """
127
        Return comma-separated list of supported sort field names.
128
        
129
        Returns:
130
        String of lowercase field names separated by commas
131
        """
132
```
133

134
#### Usage Example
135

136
```python
137
from sphinxlint.cli import SortField
138

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

142
# Use in programmatic sorting
143
sort_fields = [SortField.FILENAME, SortField.LINE]
144
```
145

146
## Programmatic Configuration
147

148
### Creating Custom Options
149

150
```python
151
from sphinxlint.sphinxlint import CheckersOptions
152

153
# Create with custom settings
154
options = CheckersOptions()
155
options.max_line_length = 100
156

157
# The options object is passed to all checker functions
158
# Individual checkers can access configuration through the options parameter
159
```
160

161
### Integration with argparse
162

163
```python
164
import argparse
165
from sphinxlint.sphinxlint import CheckersOptions
166

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

172
# Convert to CheckersOptions
173
options = CheckersOptions.from_argparse(args)
174
print(f"Max line length: {options.max_line_length}")  # Output: 120
175
```
176

177
## Configuration File Support
178

179
Currently, sphinx-lint does not support configuration files (like `.sphinx-lint.cfg` or `pyproject.toml` sections). All configuration is done through command-line arguments or programmatic API usage.
180

181
### Integration Recommendations
182

183
For project-level configuration, you can:
184

185
1. **Use Makefile targets**:
186
```makefile
187
lint-docs:
188
	sphinx-lint --max-line-length 120 --disable trailing-whitespace docs/
189
```
190

191
2. **Create shell scripts**:
192
```bash
193
#!/bin/bash
194
# lint-docs.sh
195
sphinx-lint \
196
    --max-line-length 120 \
197
    --disable trailing-whitespace,horizontal-tab \
198
    --enable line-too-long \
199
    --jobs auto \
200
    --sort-by filename,line \
201
    "$@"
202
```
203

204
3. **Use in pre-commit hooks**:
205
```yaml
206
repos:
207
  - repo: https://github.com/sphinx-contrib/sphinx-lint
208
    rev: v1.0.0
209
    hooks:
210
      - id: sphinx-lint
211
        args:
212
          - --max-line-length=120
213
          - --disable=trailing-whitespace
214
          - --enable=line-too-long
215
```
216

217
## Environment Integration
218

219
### CI/CD Configuration
220

221
```yaml
222
# GitHub Actions example
223
- name: Lint documentation
224
  run: |
225
    pip install sphinx-lint
226
    sphinx-lint \
227
      --max-line-length 88 \
228
      --enable line-too-long \
229
      --disable trailing-whitespace \
230
      --jobs auto \
231
      --sort-by filename,line \
232
      docs/
233
```
234

235
### Editor Integration
236

237
For editors that support external linters:
238

239
```json
240
// VS Code settings.json example
241
{
242
  "python.linting.enabled": true,
243
  "python.linting.sphinxLintEnabled": true,
244
  "python.linting.sphinxLintArgs": [
245
    "--max-line-length=120",
246
    "--disable=trailing-whitespace"
247
  ]
248
}
249
```
250

251
## Performance Configuration
252

253
### Parallel Processing
254

255
The CLI automatically optimizes parallel processing:
256

257
- **Files < 8**: Always single-threaded (overhead not worth it)
258
- **Files >= 8**: Uses parallel processing based on `--jobs` setting
259
- **Default**: `--jobs auto` uses `os.cpu_count()` for optimal performance
260

261
### Memory Management
262

263
- Per-file caches are automatically cleared after each file check
264
- No persistent state between file checks
265
- Memory usage scales with file size and enabled checker count