0
# rstcheck
1

2
A comprehensive Python CLI tool for checking the syntax of reStructuredText files and code blocks nested within them. rstcheck validates both the RST document structure and the syntax of embedded code blocks in multiple programming languages, making it essential for documentation quality assurance in Python projects and technical writing workflows.
3

4
## Package Information
5

6
- **Package Name**: rstcheck
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install rstcheck`
10

11
**Optional extras:**
12
- `pip install rstcheck[toml]` - TOML configuration support
13
- `pip install rstcheck[sphinx]` - Sphinx directive/role support
14

15
## Core Imports
16

17
The primary interface is the command-line tool, but programmatic access is available:
18

19
```python
20
from rstcheck import _cli
21
```
22

23
## Basic Usage
24

25
### Command Line Interface
26

27
Basic syntax checking:
28

29
```bash
30
# Check a single RST file
31
rstcheck document.rst
32

33
# Check multiple files
34
rstcheck doc1.rst doc2.rst src/readme.rst
35

36
# Check all RST files in a directory recursively
37
rstcheck --recursive docs/
38

39
# Read from stdin
40
cat document.rst | rstcheck -
41
```
42

43
### Configuration Examples
44

45
Using command-line options:
46

47
```bash
48
# Ignore specific code block languages
49
rstcheck --ignore-languages cpp,javascript document.rst
50

51
# Set report level
52
rstcheck --report-level ERROR --log-level INFO document.rst
53

54
# Use custom config file
55
rstcheck --config myproject.cfg document.rst
56

57
# Ignore custom directives and roles
58
rstcheck --ignore-directives custom-directive --ignore-roles custom-role document.rst
59
```
60

61
Using configuration file (`.rstcheck.cfg` or `pyproject.toml`):
62

63
```ini
64
[rstcheck]
65
ignore_directives = custom-directive,foobar
66
ignore_roles = custom-role
67
ignore_messages = (Title underline too short\.$)
68
ignore_languages = cpp,javascript
69
report_level = warning
70
```
71

72
## Capabilities
73

74
### File Processing
75

76
Core file processing functionality for RST syntax validation.
77

78
```bash { .api }
79
# Command: rstcheck [OPTIONS] FILES...
80
# FILES: One or more RST file paths, directories (with --recursive), or "-" for stdin
81
```
82

83
**File Input Options:**
84
- Multiple file paths: Check specific RST files
85
- Directory with `--recursive`: Recursively find and check all `.rst` files
86
- Stdin with `"-"`: Read RST content from standard input (exclusive with other files)
87

88
### Configuration Management
89

90
Configuration system supporting multiple file formats and sources.
91

92
```bash { .api }
93
# Configuration options
94
--config PATH          # Config file or directory path
95
--warn-unknown-settings # Log warnings for unknown config settings
96
```
97

98
**Configuration File Resolution:**
99
1. Path specified via `--config` option
100
2. `.rstcheck.cfg` in current or parent directories
101
3. `pyproject.toml` with `[tool.rstcheck]` section (requires toml extra)
102
4. `setup.cfg` with `[rstcheck]` section
103

104
**Supported Configuration Formats:**
105
- **INI format** (`.cfg`, `.ini` files): `[rstcheck]` section
106
- **TOML format** (`pyproject.toml`): `[tool.rstcheck]` section
107

108
### Report Level Control
109

110
Control the severity level of issues reported.
111

112
```bash { .api }
113
--report-level LEVEL   # Report level: INFO|WARNING|ERROR|SEVERE|NONE
114
--log-level LEVEL     # Application log level: DEBUG|INFO|WARNING|ERROR|CRITICAL
115
```
116

117
**Report Levels:**
118
- `INFO`: Report all issues including informational messages
119
- `WARNING`: Report warnings and above (default)
120
- `ERROR`: Report errors and severe issues only
121
- `SEVERE`: Report only severe structural issues
122
- `NONE`: Suppress all issue reporting (exit code still reflects status)
123

124
### Content Filtering
125

126
Flexible filtering system to ignore specific RST elements and code blocks.
127

128
```bash { .api }
129
--ignore-directives TEXT    # Comma-separated directives to ignore
130
--ignore-roles TEXT         # Comma-separated roles to ignore
131
--ignore-substitutions TEXT # Comma-separated substitutions to ignore
132
--ignore-languages TEXT     # Comma-separated code block languages to ignore
133
--ignore-messages REGEX     # Regular expression for messages to ignore
134
```
135

136
**Ignore Options:**
137
- **Directives**: Skip validation of custom or problematic RST directives
138
- **Roles**: Skip validation of custom or problematic RST roles
139
- **Substitutions**: Skip validation of undefined substitution references
140
- **Languages**: Skip syntax checking of code blocks in specified languages
141
- **Messages**: Skip issues matching the provided regular expression pattern
142

143
### Directory Processing
144

145
Recursive directory processing with flexible file discovery.
146

147
```bash { .api }
148
--recursive, -r        # Recursively search directories for RST files
149
```
150

151
**Directory Processing Features:**
152
- Automatic `.rst` file discovery in directory trees
153
- Configurable file filtering via configuration
154
- Preserves directory structure in error reporting
155

156
### Code Block Validation
157

158
Comprehensive syntax validation for embedded code blocks in multiple languages.
159

160
**Supported Languages:**
161
- **Bash**: Shell script syntax validation
162
- **Doctest**: Python doctest format validation
163
- **C**: C99 standard syntax checking
164
- **C++**: C++11 standard syntax checking
165
- **JSON**: JSON format validation
166
- **XML**: XML structure and syntax validation
167
- **Python**: Python syntax checking
168
- **reStructuredText**: Nested RST content validation
169

170
### Version Information
171

172
Version reporting for rstcheck and its dependencies.
173

174
```bash { .api }
175
--version              # Print version information and exit
176
```
177

178
**Version Output:**
179
- rstcheck CLI version
180
- rstcheck-core library version
181
- Enabled feature information (Sphinx, TOML support)
182

183
### Programmatic Interface
184

185
While primarily a CLI tool, programmatic access is available for integration.
186

187
```python { .api }
188
from rstcheck._cli import main, setup_logger, cli
189

190
def main() -> None:
191
    """Run the CLI application."""
192
    # Entry point for programmatic execution
193

194
def setup_logger(loglevel: str) -> None:
195
    """Set up logging configuration.
196
    
197
    Args:
198
        loglevel (str): Logging level (DEBUG|INFO|WARNING|ERROR|CRITICAL)
199
        
200
    Raises:
201
        TypeError: On invalid logging levels
202
    """
203

204
def cli(
205
    files: list[pathlib.Path],
206
    config: pathlib.Path | None = None,
207
    warn_unknown_settings: bool | None = None,
208
    recursive: bool | None = None,
209
    report_level: str | None = None,
210
    log_level: str = "WARNING",
211
    ignore_directives: str | None = None,
212
    ignore_roles: str | None = None,
213
    ignore_substitutions: str | None = None,
214
    ignore_languages: str | None = None,
215
    ignore_messages: str | None = None,
216
    version: bool | None = None,
217
) -> None:
218
    """Main CLI function with full parameter control.
219
    
220
    Args:
221
        files: List of RST file paths to check
222
        config: Path to configuration file or directory
223
        warn_unknown_settings: Log warnings for unknown config settings
224
        recursive: Recursively search directories for RST files
225
        report_level: Issue report level (INFO|WARNING|ERROR|SEVERE|NONE)
226
        log_level: Application logging level
227
        ignore_directives: Comma-separated directives to ignore
228
        ignore_roles: Comma-separated roles to ignore
229
        ignore_substitutions: Comma-separated substitutions to ignore
230
        ignore_languages: Comma-separated languages to ignore in code blocks
231
        ignore_messages: Regular expression for messages to ignore
232
        version: Print version information and exit
233
    
234
    Raises:
235
        typer.Exit: On completion (with appropriate exit code)
236
        FileNotFoundError: When specified config path is not found
237
    """
238
```
239

240
## Error Handling
241

242
rstcheck provides comprehensive error reporting with structured output.
243

244
**Exit Codes:**
245
- `0`: Success, no issues detected
246
- `1`: Issues detected or execution error
247

248
**Error Message Format:**
249
```
250
filename.rst:line: (SEVERITY/level) message context
251
```
252

253
**Common Error Categories:**
254
- **RST Structure**: Title underlines, section hierarchy, directive syntax
255
- **Code Block Syntax**: Language-specific syntax errors in embedded code
256
- **Reference Errors**: Undefined links, substitutions, or cross-references
257
- **Configuration Errors**: Invalid settings or missing config files
258

259
**Error Suppression:**
260
- Global suppression via `--report-level NONE`
261
- Selective suppression via ignore options
262
- Pattern-based suppression via `--ignore-messages`
263
- Inline suppression via RST comments (when supported by rstcheck-core)
264

265
## Integration
266

267
### Pre-commit Hook
268

269
rstcheck includes pre-commit hook configuration:
270

271
```yaml
272
repos:
273
  - repo: https://github.com/rstcheck/rstcheck
274
    rev: v6.2.5
275
    hooks:
276
      - id: rstcheck
277
        additional_dependencies: [rstcheck[sphinx,toml]]
278
```
279

280
### CI/CD Integration
281

282
Command-line interface enables easy CI/CD integration:
283

284
```bash
285
# Fail build on any RST issues
286
rstcheck --report-level ERROR docs/
287

288
# Check all documentation with custom config
289
rstcheck --recursive --config .rstcheck.cfg docs/
290
```
291

292
### Development Workflow
293

294
Integration with development tools and workflows:
295

296
- **tox**: Multi-environment testing with RST validation
297
- **pre-commit**: Automatic RST checking on commit
298
- **GitHub Actions**: Automated documentation validation
299
- **Sphinx**: Documentation build pipeline integration
300

301
## Dependencies
302

303
**Required Dependencies:**
304
- `rstcheck-core >=1.1`: Core RST checking functionality
305
- `typer >=0.12.0`: Modern CLI framework
306

307
**Optional Dependencies:**
308
- `sphinx >=6.0`: Sphinx directive and role support
309
- `tomli >=2.0` (Python ≤3.10): TOML configuration file support
310

311
## Performance Considerations
312

313
- **File Processing**: Efficient batch processing of multiple files
314
- **Directory Scanning**: Optimized recursive directory traversal
315
- **Memory Usage**: Streaming file processing for large documents
316
- **Parallel Processing**: Single-threaded but optimized for CI/CD pipelines
317

318
## Advanced Configuration
319

320
### Custom Directive Support
321

322
Configure rstcheck to recognize project-specific RST extensions:
323

324
```ini
325
[rstcheck]
326
ignore_directives = 
327
    custom-directive,
328
    project-specific-directive,
329
    legacy-directive
330
ignore_roles = 
331
    custom-role,
332
    domain-specific-role
333
```
334

335
### Language-Specific Settings
336

337
Fine-tune code block validation for your project's needs:
338

339
```ini
340
[rstcheck]
341
# Skip validation for languages not relevant to your project
342
ignore_languages = cpp,rust,go
343
# Focus on critical languages
344
report_level = ERROR
345
```
346

347
### Message Filtering
348

349
Use regular expressions to suppress specific known issues:
350

351
```ini
352
[rstcheck]
353
# Suppress title underline warnings for specific patterns
354
ignore_messages = (Title underline too short for title.*\.$)|(Unknown directive type.*\.$)
355
```