0
# Docstring Processing
1

2
Multi-format docstring conversion supporting Markdown, Google, NumPy, and reStructuredText styles with cross-reference linking. Transforms various docstring formats into clean HTML with automatic identifier linking and enhanced formatting.
3

4
## Capabilities
5

6
### Multi-Format Conversion
7

8
Convert docstrings from various formats to HTML with intelligent processing.
9

10
```python { .api }
11
@cache
12
def convert(docstring: str, docformat: str, source_file: Path | None) -> str:
13
    """
14
    Convert docstring from docformat to Markdown.
15
    
16
    Parameters:
17
    - docstring: str - Raw docstring content
18
    - docformat: str - Source format (google, numpy, restructuredtext, markdown)
19
    - source_file: Path | None - Source file path for relative references
20
    
21
    Returns:
22
    - str: Converted Markdown content
23
    
24
    Raises:
25
    - RuntimeError: If docstring processing fails
26
    """
27
```
28

29
### Google-Style Docstrings
30

31
Process Google-style docstrings with structured sections.
32

33
```python { .api }
34
def google(docstring: str) -> str:
35
    """
36
    Convert Google-style docstring sections into Markdown.
37
    
38
    Parameters:
39
    - docstring: str - Google-style docstring
40
    
41
    Returns:
42
    - str: Markdown-formatted docstring
43
    
44
    Supported sections:
45
    - Args/Arguments/Parameters
46
    - Returns/Return
47
    - Yields/Yield
48
    - Raises/Except/Exceptions
49
    - Note/Notes
50
    - Example/Examples
51
    - Attributes
52
    - References
53
    """
54
```
55

56
### Image Embedding
57

58
Embed local images directly into documentation as data URIs.
59

60
```python { .api }
61
def embed_images(docstring: str, source_file: Path) -> str:
62
    """
63
    Embed local images referenced in docstrings as data URIs.
64
    
65
    Parameters:
66
    - docstring: str - Docstring text potentially containing image references
67
    - source_file: Path - Source file path for resolving relative image paths
68
    
69
    Returns:
70
    - str: Docstring with local images converted to data URIs
71
    
72
    Features:
73
    - Converts Markdown image syntax ![alt](path) to data URIs
74
    - Converts HTML img src attributes to data URIs
75
    - Automatic MIME type detection
76
    - Base64 encoding for binary image data
77
    """
78
```
79

80
### NumPy-Style Docstrings
81

82
Process NumPy-style docstrings with scientific documentation conventions.
83

84
```python { .api }
85
def numpy(docstring: str) -> str:
86
    """
87
    Convert NumPy-style docstring sections into Markdown.
88
    
89
    Parameters:
90
    - docstring: str - NumPy-style docstring
91
    
92
    Returns:
93
    - str: Markdown-formatted docstring
94
    
95
    Supported sections:
96
    - Parameters
97
    - Returns
98
    - Yields
99
    - Raises
100
    - See Also
101
    - Notes
102
    - References
103
    - Examples
104
    """
105
```
106

107
### reStructuredText Processing
108

109
Process reStructuredText docstrings with Sphinx-compatible features.
110

111
```python { .api }
112
def rst(contents: str, source_file: Path | None) -> str:
113
    """
114
    Convert reStructuredText syntax elements to Markdown.
115
    
116
    Parameters:
117
    - contents: str - reStructuredText content  
118
    - source_file: Path | None - Source file for resolving relative paths
119
    
120
    Returns:
121
    - str: Markdown-converted content
122
    
123
    Supported features:
124
    - Standard rST directives
125
    - Code blocks with syntax highlighting
126
    - Cross-references and hyperlinks
127
    - Include directives for external files
128
    """
129
```
130

131
### Image Embedding
132

133
Embed images referenced in docstrings as base64 data URIs.
134

135
```python { .api }
136
def embed_images(html: str) -> str:
137
    """
138
    Embed image references as base64 data URIs.
139
    
140
    Parameters:
141
    - html: str - HTML content with image references
142
    
143
    Returns:
144
    - str: HTML with embedded image data
145
    
146
    Features:
147
    - Converts local image paths to base64 data URIs
148
    - Maintains image accessibility and alt text
149
    - Reduces external dependencies in generated docs
150
    """
151
```
152

153
## Usage Examples
154

155
### Basic Docstring Conversion
156

157
```python
158
from pdoc.docstrings import convert
159

160
# Convert different docstring formats
161
google_doc = '''
162
    Process data with advanced algorithms.
163
    
164
    Args:
165
        data (list): Input data to process
166
        method (str): Processing method ('fast' or 'accurate')
167
        
168
    Returns:
169
        dict: Processed results with metadata
170
        
171
    Raises:
172
        ValueError: If method is not recognized
173
'''
174

175
html_output = convert(google_doc, docformat="google")
176
print(html_output)  # HTML with structured sections
177
```
178

179
### Format-Specific Processing
180

181
```python
182
from pdoc.docstrings import google, numpy, rst
183

184
# Google-style docstring
185
google_text = '''
186
    Calculate statistics.
187
    
188
    Args:
189
        values: List of numeric values
190
        
191
    Returns:
192
        Statistical summary dictionary
193
'''
194
google_html = google(google_text)
195

196
# NumPy-style docstring  
197
numpy_text = '''
198
    Calculate statistics.
199
    
200
    Parameters
201
    ----------
202
    values : array_like
203
        List of numeric values
204
        
205
    Returns
206
    -------
207
    dict
208
        Statistical summary
209
'''
210
numpy_html = numpy(numpy_text)
211

212
# reStructuredText docstring
213
rst_text = '''
214
    Calculate statistics.
215
    
216
    :param values: List of numeric values
217
    :type values: list
218
    :returns: Statistical summary
219
    :rtype: dict
220
'''
221
rst_html = rst(rst_text)
222
```
223

224
### Advanced Processing with Context
225

226
```python
227
from pdoc.docstrings import convert
228
from pdoc import render
229

230
# Configure docstring processing globally
231
render.configure(
232
    docformat="google",
233
    math=True,      # Enable LaTeX math
234
    mermaid=True    # Enable Mermaid diagrams
235
)
236

237
# Docstring with math and diagrams
238
advanced_docstring = '''
239
    Solve quadratic equation using the quadratic formula.
240
    
241
    The quadratic formula is: $x = \\frac{-b \\pm \\sqrt{b^2-4ac}}{2a}$
242
    
243
    Args:
244
        a (float): Coefficient of x²
245
        b (float): Coefficient of x  
246
        c (float): Constant term
247
        
248
    Returns:
249
        tuple: Two solutions (x1, x2)
250
        
251
    Example:
252
        ```mermaid
253
        graph TD
254
            A[Input: a,b,c] --> B[Calculate discriminant]
255
            B --> C{discriminant >= 0?}
256
            C -->|Yes| D[Two real solutions]
257
            C -->|No| E[Complex solutions]
258
        ```
259
'''
260

261
html_with_features = convert(advanced_docstring, "google")
262
```
263

264
### Image Embedding
265

266
```python
267
from pdoc.docstrings import embed_images, convert
268

269
# Docstring with image references
270
doc_with_images = '''
271
    Process image data.
272
    
273
    ![Algorithm Diagram](./docs/algorithm.png)
274
    
275
    The algorithm works as shown in the diagram above.
276
'''
277

278
# Convert to HTML
279
html_content = convert(doc_with_images, "markdown")
280

281
# Embed images as base64
282
embedded_html = embed_images(html_content)
283
# Images are now embedded in the HTML as data URIs
284
```
285

286
### Custom Docstring Processing Pipeline
287

288
```python
289
from pdoc.docstrings import convert, embed_images
290
import re
291

292
def process_custom_docstring(docstring: str, docformat: str = "google") -> str:
293
    """Custom docstring processing with additional features"""
294
    
295
    # Pre-process: Handle custom tags
296
    docstring = re.sub(r'@deprecated', '**Deprecated:**', docstring)
297
    docstring = re.sub(r'@since (.+)', r'*Since version \1*', docstring)
298
    
299
    # Convert using pdoc
300
    html = convert(docstring, docformat)
301
    
302
    # Post-process: Embed images
303
    html = embed_images(html)
304
    
305
    # Add custom styling
306
    html = html.replace('<code>', '<code class="custom-code">')
307
    
308
    return html
309

310
# Usage
311
custom_doc = '''
312
    @deprecated
313
    This function is deprecated since version 2.0.
314
    
315
    @since 1.0
316
    
317
    Args:
318
        data: Input data
319
        
320
    Returns:
321
        Processed result
322
'''
323

324
processed_html = process_custom_docstring(custom_doc)
325
```
326

327
### Integration with Documentation Objects
328

329
```python
330
from pdoc import doc
331
from pdoc.docstrings import convert
332

333
# Process docstrings from actual Python objects
334
module_obj = doc.Module.from_name("my_package")
335

336
for name, member in module_obj.members.items():
337
    if hasattr(member.obj, '__doc__') and member.obj.__doc__:
338
        raw_docstring = member.obj.__doc__
339
        processed_html = convert(raw_docstring, "google")
340
        print(f"{name}: {processed_html[:100]}...")
341
```
342

343
## Constants and Configuration
344

345
### Section Recognition
346

347
```python { .api }
348
GOOGLE_LIST_SECTIONS: list[str]
349
"""
350
List of recognized Google docstring section names:
351
['Args', 'Arguments', 'Parameters', 'Param', 'Params', 'Return', 'Returns', 
352
 'Yield', 'Yields', 'Raise', 'Raises', 'Except', 'Exceptions', 'Attributes', 
353
 'Example', 'Examples', 'Keyword Arguments', 'Keyword Args', 'Note', 'Notes', 
354
 'Other Parameters', 'References', 'See Also']
355
"""
356

357
GOOGLE_LIST_SECTION_ALIASES: dict[str, str]
358
"""
359
Mapping of section aliases to canonical names:
360
{'Param': 'Parameters', 'Params': 'Parameters', 'Return': 'Returns', 
361
 'Yield': 'Yields', 'Raise': 'Raises', 'Except': 'Exceptions', ...}
362
"""
363
```
364

365
### Exception Handling
366

367
```python { .api }
368
AnyException: tuple[type[Exception], ...]
369
"""
370
Tuple of exception types for docstring processing error handling.
371
Includes various exception types that may be raised during parsing.
372
"""
373
```
374

375
## Error Handling
376

377
The docstring processing system gracefully handles various error conditions:
378

379
- **Malformed docstrings**: Returns original text with minimal formatting
380
- **Invalid markup**: Escapes problematic characters and continues processing
381
- **Missing references**: Leaves unresolved references as plain text
382
- **Image loading errors**: Falls back to original image references
383
- **Math rendering errors**: Shows LaTeX source code if rendering fails