0
# Core Documentation API
1
2
The main API for generating documentation from Python source code. These functions provide the primary interface for programmatic documentation generation with various output formats and customization options.
3
4
## Capabilities
5
6
### HTML Documentation Generation
7
8
Generate self-contained HTML documentation from Python modules with full styling, cross-linking, and optional minification.
9
10
```python { .api }
11
def html(module_name, docfilter=None, reload=False, skip_errors=False, **kwargs) -> str:
12
"""
13
Returns the documentation for the module in HTML format.
14
15
Parameters:
16
- module_name: Module name or importable string
17
- docfilter: Optional predicate function that controls which documentation
18
objects are shown (takes Doc object, returns bool)
19
- reload: If True, reload the module before generating documentation
20
- skip_errors: If True, warn instead of raising on import errors
21
- **kwargs: Additional template configuration options
22
23
Returns:
24
str: Self-contained HTML documentation
25
"""
26
```
27
28
### Text Documentation Generation
29
30
Generate plain text documentation suitable for terminal viewing or text-based documentation systems.
31
32
```python { .api }
33
def text(module_name, docfilter=None, reload=False, skip_errors=False, **kwargs) -> str:
34
"""
35
Returns the documentation for the module in plain text format.
36
37
Parameters:
38
- module_name: Module name or importable string
39
- docfilter: Optional predicate function for filtering documentation objects
40
- reload: If True, reload the module before generating documentation
41
- skip_errors: If True, warn instead of raising on import errors
42
- **kwargs: Additional template configuration options
43
44
Returns:
45
str: Plain text documentation suitable for terminal viewing
46
"""
47
```
48
49
### Module Import and Management
50
51
Import and manage Python modules for documentation processing with support for filesystem paths and error handling.
52
53
```python { .api }
54
def import_module(module, reload=False, skip_errors=False) -> ModuleType:
55
"""
56
Return module object matching module specification.
57
58
Parameters:
59
- module: Module specification (python module path or filesystem path)
60
- reload: If True, reload module if already imported
61
- skip_errors: If True, warn instead of raising on import errors
62
63
Returns:
64
ModuleType: Imported module object
65
"""
66
```
67
68
### Context and State Management
69
70
Manage global documentation context and reset caches for clean documentation generation.
71
72
```python { .api }
73
def reset() -> None:
74
"""
75
Resets the global Context to the initial (empty) state.
76
77
Clears all cached documentation objects and LRU caches for:
78
- Type hints cache
79
- Blacklist/whitelist caches
80
- Doc object method caches
81
"""
82
83
def link_inheritance(context=None) -> None:
84
"""
85
Link inheritance relationships between Class objects and their members.
86
87
Parameters:
88
- context: Optional Context to use (defaults to global context)
89
90
This must be called for Doc.inherits and inherited docstrings to be set correctly.
91
"""
92
```
93
94
### Module Documentation Objects
95
96
Create and manipulate Module objects for advanced documentation processing and customization.
97
98
```python { .api }
99
class Module(Doc):
100
def __init__(self, module, docfilter=None, supermodule=None, context=None, skip_errors=False):
101
"""
102
Creates a Module documentation object.
103
104
Parameters:
105
- module: Module object or importable string
106
- docfilter: Optional predicate that controls which sub-objects are documented
107
- supermodule: Parent Module if this is a submodule
108
- context: Context instance for cross-referencing (defaults to global)
109
- skip_errors: If True, warn instead of raising on unimportable submodules
110
"""
111
112
def html(self, minify=True, **kwargs) -> str:
113
"""
114
Returns HTML documentation for this module.
115
116
Parameters:
117
- minify: If True, minify the resulting HTML
118
- **kwargs: Template configuration options
119
120
Returns:
121
str: Self-contained HTML documentation
122
"""
123
124
def text(self, **kwargs) -> str:
125
"""
126
Returns plain text documentation for this module.
127
128
Parameters:
129
- **kwargs: Template configuration options
130
131
Returns:
132
str: Plain text documentation
133
"""
134
135
def find_class(self, cls: type) -> Doc:
136
"""
137
Find a class documentation object in this module or submodules.
138
139
Parameters:
140
- cls: Python class object
141
142
Returns:
143
Doc: Class documentation object or External if not found
144
"""
145
146
def find_ident(self, name: str) -> Doc:
147
"""
148
Find identifier documentation object by name.
149
150
Parameters:
151
- name: Identifier name to search for
152
153
Returns:
154
Doc: Documentation object or External if not found
155
"""
156
157
def variables(self, sort=True) -> List['Variable']:
158
"""
159
Returns all documented module-level variables.
160
161
Parameters:
162
- sort: If True, sort alphabetically
163
164
Returns:
165
List[Variable]: Module variables
166
"""
167
168
def classes(self, sort=True) -> List['Class']:
169
"""
170
Returns all documented module-level classes.
171
172
Parameters:
173
- sort: If True, sort alphabetically
174
175
Returns:
176
List[Class]: Module classes
177
"""
178
179
def functions(self, sort=True) -> List['Function']:
180
"""
181
Returns all documented module-level functions.
182
183
Parameters:
184
- sort: If True, sort alphabetically
185
186
Returns:
187
List[Function]: Module functions
188
"""
189
190
def submodules(self) -> List['Module']:
191
"""
192
Returns all documented sub-modules sorted alphabetically.
193
194
Returns:
195
List[Module]: Submodules
196
"""
197
```
198
199
### Context Management
200
201
Global context for cross-referencing between documentation objects and modules.
202
203
```python { .api }
204
class Context(dict):
205
def __init__(self, *args, **kwargs):
206
"""
207
Context object that maps documented identifiers to their Doc objects.
208
209
All Module objects that share the same Context will see and be able
210
to link to each other's identifiers.
211
"""
212
```
213
214
## Usage Examples
215
216
### Basic Documentation Generation
217
218
```python
219
import pdoc
220
221
# Generate documentation for a single module
222
doc = pdoc.html('numpy')
223
224
# Generate with custom filter to exclude private members
225
def public_only(doc_obj):
226
return not doc_obj.name.startswith('_')
227
228
filtered_doc = pdoc.html('mymodule', docfilter=public_only)
229
```
230
231
### Advanced Module Processing
232
233
```python
234
import pdoc
235
236
# Create shared context for multiple modules
237
context = pdoc.Context()
238
239
# Process multiple related modules
240
modules = []
241
for module_name in ['mypackage.core', 'mypackage.utils', 'mypackage.api']:
242
module = pdoc.Module(module_name, context=context)
243
modules.append(module)
244
245
# Link inheritance across all modules
246
pdoc.link_inheritance(context)
247
248
# Generate documentation for each module
249
for module in modules:
250
html_doc = module.html(show_source=True, external_links=True)
251
with open(f'{module.name}.html', 'w') as f:
252
f.write(html_doc)
253
```
254
255
### Error Handling and Debugging
256
257
```python
258
import pdoc
259
260
try:
261
# Attempt to generate documentation
262
doc = pdoc.html('problematic_module')
263
except ImportError as e:
264
print(f"Import failed: {e}")
265
# Use skip_errors to continue processing
266
doc = pdoc.html('problematic_module', skip_errors=True)
267
268
# Reset global state between runs
269
pdoc.reset()
270
```