0
# Docstring Processing
1

2
Comprehensive docstring transformation and enhancement through configurable processors that filter content, resolve cross-references, and convert between documentation formats.
3

4
## Capabilities
5

6
### Filter Processing
7

8
Removes module and class members based on configurable criteria including visibility, documentation status, and custom expressions.
9

10
```python { .api }
11
class FilterProcessor(Processor):
12
    """
13
    Filter processor removes API objects based on specified criteria.
14
    
15
    Attributes:
16
        expression: Python expression evaluated with variables 'name', 'obj', and 'default()'
17
                   to determine if object should be kept (default: None)
18
        documented_only: Only include objects with docstrings (default: True)
19
        do_not_filter_modules: Never filter out modules (default: False)  
20
        skip_empty_modules: Remove modules with no remaining members after filtering (default: True)
21
    """
22
    expression: Optional[str]
23
    documented_only: bool
24
    do_not_filter_modules: bool
25
    skip_empty_modules: bool
26
    
27
    def process(self, modules: List[docspec.Module], resolver: Optional[Resolver]) -> None:
28
        """
29
        Apply filtering rules to remove unwanted API objects.
30
        
31
        Args:
32
            modules: List of modules to filter
33
            resolver: Optional resolver for cross-references
34
        """
35
```
36

37
### Cross-Reference Processing
38

39
Processes cross-references in docstrings, converting references to other API objects into hyperlinks.
40

41
```python { .api }
42
class CrossrefProcessor(Processor):
43
    """
44
    Process cross-references in docstrings and convert them to hyperlinks.
45
    
46
    Attributes:
47
        resolver_v2: Optional resolver for reference resolution (default: None)
48
    """
49
    resolver_v2: Optional[ResolverV2]
50
    
51
    def process(self, modules: List[docspec.Module], resolver: Optional[Resolver]) -> None:
52
        """
53
        Process cross-references in docstrings.
54
        
55
        Args:
56
            modules: List of modules to process
57
            resolver: Resolver for converting references to hyperlinks
58
        """
59
```
60

61
### Google Style Processing
62

63
Converts Google-style docstrings to Markdown format with proper argument, return value, and exception documentation.
64

65
```python { .api }
66
class GoogleProcessor(Processor):
67
    """
68
    Process Google-style docstrings and convert them to Markdown.
69
    
70
    Handles sections like Args:, Returns:, Raises:, Yields:, Note:, Example:
71
    """
72
    
73
    def process(self, modules: List[docspec.Module], resolver: Optional[Resolver]) -> None:
74
        """
75
        Convert Google-style docstrings to Markdown format.
76
        
77
        Args:
78
            modules: List of modules to process
79
            resolver: Optional resolver for cross-references
80
        """
81
```
82

83
### Sphinx Style Processing
84

85
Converts Sphinx-style docstrings (reStructuredText) to Markdown format with proper formatting of parameters, return values, and other documentation elements.
86

87
```python { .api }
88
class SphinxProcessor(Processor):
89
    """
90
    Process Sphinx-style docstrings and convert them to Markdown.
91
    
92
    Handles reStructuredText directives like :param:, :returns:, :raises:, etc.
93
    """
94
    
95
    def process(self, modules: List[docspec.Module], resolver: Optional[Resolver]) -> None:
96
        """
97
        Convert Sphinx-style docstrings to Markdown format.
98
        
99
        Args:
100
            modules: List of modules to process  
101
            resolver: Optional resolver for cross-references
102
        """
103
```
104

105
### Smart Processing
106

107
Applies intelligent formatting and enhancements to docstrings including code block detection, list formatting, and automatic improvements.
108

109
```python { .api }
110
class SmartProcessor(Processor):
111
    """
112
    Apply smart formatting enhancements to docstrings.
113
    
114
    Automatically detects and formats code blocks, lists, and other common
115
    documentation patterns for improved Markdown output.
116
    """
117
    
118
    def process(self, modules: List[docspec.Module], resolver: Optional[Resolver]) -> None:
119
        """
120
        Apply smart formatting to docstrings.
121
        
122
        Args:
123
            modules: List of modules to process
124
            resolver: Optional resolver for cross-references  
125
        """
126
```
127

128
### Pydoc-Markdown Style Processing
129

130
Processes Pydoc-Markdown's native docstring format with custom extensions and formatting rules.
131

132
```python { .api }
133
class PydocmdProcessor(Processor):
134
    """
135
    Process Pydoc-Markdown native docstring format.
136
    
137
    Handles custom Pydoc-Markdown syntax and formatting extensions.
138
    """
139
    
140
    def process(self, modules: List[docspec.Module], resolver: Optional[Resolver]) -> None:
141
        """
142
        Process Pydoc-Markdown format docstrings.
143
        
144
        Args:
145
            modules: List of modules to process
146
            resolver: Optional resolver for cross-references
147
        """
148
```
149

150
## Usage Examples
151

152
### Basic Filtering
153

154
```python
155
from pydoc_markdown import PydocMarkdown
156
from pydoc_markdown.contrib.processors.filter import FilterProcessor
157

158
# Only include documented public members
159
processor = FilterProcessor(
160
    documented_only=True,
161
    expression="not name.startswith('_')"
162
)
163

164
config = PydocMarkdown(processors=[processor])
165
```
166

167
### Advanced Filtering
168

169
```python
170
from pydoc_markdown.contrib.processors.filter import FilterProcessor
171

172
# Complex filtering with custom expression
173
processor = FilterProcessor(
174
    expression="not name.startswith('_') and 'deprecated' not in (obj.docstring or '').lower()",
175
    documented_only=True,
176
    skip_empty_modules=True
177
)
178
```
179

180
### Cross-Reference Processing
181

182
```python
183
from pydoc_markdown.contrib.processors.crossref import CrossrefProcessor
184

185
# Enable cross-reference resolution
186
processor = CrossrefProcessor()
187

188
config = PydocMarkdown(processors=[processor])
189
```
190

191
### Google Style Docstrings
192

193
```python
194
from pydoc_markdown.contrib.processors.google import GoogleProcessor
195

196
# Convert Google-style docstrings
197
processor = GoogleProcessor()
198

199
# Example docstring it processes:
200
"""
201
Calculate the area of a rectangle.
202

203
Args:
204
    width (float): The width of the rectangle.
205
    height (float): The height of the rectangle.
206

207
Returns:
208
    float: The area of the rectangle.
209

210
Raises:
211
    ValueError: If width or height is negative.
212
"""
213
```
214

215
### Sphinx Style Docstrings
216

217
```python
218
from pydoc_markdown.contrib.processors.sphinx import SphinxProcessor
219

220
# Convert Sphinx-style docstrings  
221
processor = SphinxProcessor()
222

223
# Example docstring it processes:
224
"""
225
Calculate the area of a rectangle.
226

227
:param width: The width of the rectangle
228
:type width: float
229
:param height: The height of the rectangle  
230
:type height: float
231
:returns: The area of the rectangle
232
:rtype: float
233
:raises ValueError: If width or height is negative
234
"""
235
```
236

237
### Combined Processing Pipeline
238

239
```python
240
from pydoc_markdown import PydocMarkdown
241
from pydoc_markdown.contrib.processors.filter import FilterProcessor
242
from pydoc_markdown.contrib.processors.google import GoogleProcessor
243
from pydoc_markdown.contrib.processors.smart import SmartProcessor
244
from pydoc_markdown.contrib.processors.crossref import CrossrefProcessor
245

246
# Comprehensive processor pipeline
247
config = PydocMarkdown(
248
    processors=[
249
        FilterProcessor(
250
            documented_only=True,
251
            expression="not name.startswith('_') and default()"
252
        ),
253
        GoogleProcessor(),  # Convert Google-style docstrings
254
        SmartProcessor(),   # Apply smart formatting
255
        CrossrefProcessor()  # Resolve cross-references
256
    ]
257
)
258
```
259

260
## Configuration Examples
261

262
### YAML Configuration
263

264
```yaml
265
processors:
266
  # Filter undocumented and private members
267
  - type: filter
268
    documented_only: true
269
    expression: "not name.startswith('_') and default()"
270
    skip_empty_modules: true
271
    
272
  # Convert Google-style docstrings
273
  - type: google
274
  
275
  # Apply smart formatting  
276
  - type: smart
277
  
278
  # Resolve cross-references
279
  - type: crossref
280
```
281

282
### Advanced Filtering Configuration
283

284
```yaml
285
processors:
286
  - type: filter
287
    # Custom expression for complex filtering
288
    expression: |
289
      (not name.startswith('_')) and 
290
      ('deprecated' not in (obj.docstring or '').lower()) and
291
      (not hasattr(obj, 'decorations') or 
292
       not any(d.name == 'private' for d in (obj.decorations or []))) and
293
      default()
294
    documented_only: true
295
    do_not_filter_modules: false
296
    skip_empty_modules: true
297
```
298

299
### Docstring Format Specific Processing
300

301
```yaml
302
# For Google-style docstrings
303
processors:
304
  - type: filter
305
  - type: google
306
  - type: smart  
307
  - type: crossref
308

309
# For Sphinx-style docstrings  
310
processors:
311
  - type: filter
312
  - type: sphinx
313
  - type: smart
314
  - type: crossref
315

316
# For mixed formats
317
processors:
318
  - type: filter
319
  - type: google
320
  - type: sphinx  
321
  - type: pydocmd
322
  - type: smart
323
  - type: crossref
324
```
325

326
## Processing Order
327

328
The order of processors matters. Recommended processing pipeline:
329

330
1. **FilterProcessor**: Remove unwanted objects early
331
2. **Format Processors**: Convert docstring formats (google/sphinx/pydocmd)
332
3. **SmartProcessor**: Apply intelligent formatting enhancements  
333
4. **CrossrefProcessor**: Resolve cross-references last (after all content is formatted)
334

335
```python
336
processors = [
337
    FilterProcessor(),      # 1. Filter content
338
    GoogleProcessor(),      # 2. Convert docstring format
339
    SmartProcessor(),       # 3. Apply smart formatting
340
    CrossrefProcessor()     # 4. Resolve cross-references
341
]
342
```