0
# flake8-rst-docstrings
1

2
A flake8 plugin that validates Python docstrings as reStructuredText (RST) markup using the docutils library. This plugin helps ensure that your docstrings conform to proper RST syntax, preventing documentation generation failures when using tools like Sphinx.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```python
14
import flake8_rst_docstrings
15
```
16

17
Accessing the main checker class:
18

19
```python
20
from flake8_rst_docstrings import reStructuredTextChecker
21
```
22

23
Accessing utility functions:
24

25
```python
26
from flake8_rst_docstrings import code_mapping
27
```
28

29
## Basic Usage
30

31
This package is designed to be used as a flake8 plugin and integrates automatically when installed:
32

33
```bash
34
# Install the plugin
35
pip install flake8-rst-docstrings
36

37
# Run flake8 with RST validation
38
flake8 --select=RST your_file.py
39

40
# Configure additional RST directives, roles, or substitutions
41
flake8 --rst-directives=mydirective,anotherdirective \
42
       --rst-roles=myrole \
43
       --rst-substitutions=mysubst \
44
       your_file.py
45
```
46

47
The plugin automatically validates docstrings in Python files and reports RST markup errors with specific error codes.
48

49
## Capabilities
50

51
### Plugin Registration
52

53
The package registers as a flake8 extension through setuptools entry points.
54

55
```python { .api }
56
# Entry point configuration in pyproject.toml:
57
# [project.entry-points]
58
# 'flake8.extension' = {RST = 'flake8_rst_docstrings:reStructuredTextChecker'}
59
```
60

61
### Main Checker Class
62

63
The core functionality is provided by the reStructuredTextChecker class that integrates with flake8's plugin system.
64

65
```python { .api }
66
class reStructuredTextChecker:
67
    """Checker of Python docstrings as reStructuredText."""
68
    
69
    name: str = "rst-docstrings"
70
    version: str
71
    
72
    def __init__(self, tree, filename="(none)"):
73
        """
74
        Initialize the checker.
75
        
76
        Args:
77
            tree: AST tree from flake8
78
            filename (str): Source filename (default: "(none)")
79
        """
80
    
81
    @classmethod
82
    def add_options(cls, parser):
83
        """
84
        Add RST directives, roles and substitutions options to flake8 parser.
85
        
86
        Args:
87
            parser: flake8 options parser
88
            
89
        Adds the following options:
90
        - --rst-directives: Comma-separated list of additional RST directives
91
        - --rst-roles: Comma-separated list of additional RST roles  
92
        - --rst-substitutions: Comma-separated list of additional RST substitutions
93
        """
94
    
95
    @classmethod
96
    def parse_options(cls, options):
97
        """
98
        Parse and store plugin configuration options.
99
        
100
        Args:
101
            options: parsed options object
102
            
103
        Sets class attributes:
104
        - extra_directives: List of additional allowed directives
105
        - extra_roles: List of additional allowed roles
106
        - extra_substitutions: List of additional allowed substitutions
107
        """
108
    
109
    def run(self):
110
        """
111
        Main validation logic - walks AST, extracts docstrings, validates RST.
112
        
113
        Returns:
114
            Generator yielding tuples of (line, column, message, checker_type)
115
            
116
        Process:
117
        1. Walks AST for modules, classes, functions, async functions
118
        2. Extracts docstrings using ast.get_docstring()
119
        3. Strips Python signatures using py_ext_sig_re
120
        4. Validates RST using restructuredtext_lint.lint()
121
        5. Maps validation errors to flake8 codes using code_mapping()
122
        6. Yields formatted error messages with line numbers
123
        """
124
```
125

126
### Error Code Mapping
127

128
Utility function for converting docutils validation messages to flake8 error codes.
129

130
```python { .api }
131
def code_mapping(level, msg, extra_directives, extra_roles, extra_substitutions, default=99):
132
    """
133
    Map RST validation messages and levels to flake8 error codes.
134
    
135
    Args:
136
        level (int): Error level (1-4)
137
        msg (str): Error message from docutils
138
        extra_directives (list): Additional allowed RST directives
139
        extra_roles (list): Additional allowed RST roles
140
        extra_substitutions (list): Additional allowed RST substitutions
141
        default (int): Default error code if no mapping found (default: 99)
142
    
143
    Returns:
144
        int: Error code between 0-99, or 0 if error should be ignored
145
    """
146
```
147

148
### Version Information
149

150
```python { .api }
151
__version__: str
152
```
153

154
The package version string.
155

156
### Constants and Configuration
157

158
```python { .api }
159
rst_prefix: str = "RST"
160
rst_fail_load: int = 900
161
rst_fail_lint: int = 903
162
py_ext_sig_re: Pattern
163
```
164

165
Configuration constants used by the checker:
166

167
- `rst_prefix`: Error code prefix for flake8 messages
168
- `rst_fail_load`: Error code for file load failures  
169
- `rst_fail_lint`: Error code for linting failures
170
- `py_ext_sig_re`: Compiled regex for matching Python extension signatures
171

172
### Error Code Mappings
173

174
```python { .api }
175
code_mapping_info: dict
176
code_mapping_warning: dict  
177
code_mapping_error: dict
178
code_mapping_severe: dict
179
code_mappings_by_level: dict
180
```
181

182
Dictionaries mapping RST validation messages to numeric error codes:
183

184
- `code_mapping_info`: Level 1 (info) message mappings
185
- `code_mapping_warning`: Level 2 (warning) message mappings
186
- `code_mapping_error`: Level 3 (error) message mappings  
187
- `code_mapping_severe`: Level 4 (severe) message mappings
188
- `code_mappings_by_level`: Master mapping of levels to their code mappings
189

190
## Error Code System
191

192
The plugin uses a structured error code system with the "RST" prefix:
193

194
- **RST1xx**: Info level (currently unused in practice)
195
- **RST2xx**: Warning level (codes 201-220) - Issues that should be addressed
196
- **RST3xx**: Error level (codes 301-307) - Major issues that must be addressed
197
- **RST4xx**: Severe level (code 401) - Critical errors that halt processing
198
- **RST9xx**: System errors (codes 900, 903) - File loading or linting failures
199

200
Common warning codes include:
201
- RST201: Block quote ends without a blank line
202
- RST202: Bullet list ends without a blank line  
203
- RST210: Inline strong start-string without end-string
204
- RST212: Title underline too short
205

206
Common error codes include:
207
- RST301: Unexpected indentation
208
- RST302: Malformed table
209
- RST303: Unknown directive type
210
- RST304: Unknown interpreted text role
211
- RST305: Undefined substitution referenced
212

213
## Configuration
214

215
Users can configure the plugin via flake8 configuration files or command line:
216

217
```ini
218
# In setup.cfg or tox.ini
219
[flake8]
220
rst-directives = custom-directive,another-directive
221
rst-roles = custom-role
222
rst-substitutions = custom-substitution
223
```
224

225
```bash
226
# Command line
227
flake8 --rst-directives=custom-directive --rst-roles=custom-role
228
```
229

230
These options allow recognition of additional RST constructs beyond the standard set, preventing false positives for project-specific or Sphinx-specific RST extensions.