0
# pdoc3
1

2
Auto-generates API documentation for Python 3+ projects from source code and docstrings. pdoc3 provides comprehensive documentation generation with support for multiple docstring formats (Markdown, numpydoc, Google-style), type annotations (PEP 484/526), automatic cross-linking, docstring inheritance, customizable templates, and a built-in development web server for real-time preview.
3

4
## Package Information
5

6
- **Package Name**: pdoc3
7
- **Language**: Python
8
- **Installation**: `pip install pdoc3`
9
- **Python Requirements**: Python 3.9+
10

11
## Core Imports
12

13
```python
14
import pdoc
15
```
16

17
For CLI usage:
18
```python
19
from pdoc.cli import main
20
```
21

22
For HTML processing utilities:
23
```python
24
from pdoc.html_helpers import to_html, to_markdown
25
```
26

27
## Basic Usage
28

29
### Simple Documentation Generation
30

31
```python
32
import pdoc
33

34
# Generate HTML documentation for a module
35
html_doc = pdoc.html('mymodule')
36

37
# Generate plain text documentation
38
text_doc = pdoc.text('mymodule')
39

40
# Save to file
41
with open('mymodule.html', 'w') as f:
42
    f.write(html_doc)
43
```
44

45
### Advanced Usage with Module Objects
46

47
```python
48
import pdoc
49

50
# Create Module documentation object
51
module = pdoc.Module('mymodule')
52

53
# Link inheritance relationships for complete documentation
54
pdoc.link_inheritance()
55

56
# Generate HTML with custom template configuration
57
html_doc = module.html(
58
    minify=True,
59
    show_source=True,
60
    external_links=True
61
)
62
```
63

64
### Command Line Usage
65

66
```python
67
from pdoc.cli import main
68

69
# Generate HTML documentation
70
main(['mymodule', '--html', '--output-dir', './docs'])
71

72
# Start development server
73
main(['mymodule', '--http', ':8080'])
74

75
# Generate documentation with custom template
76
main(['mymodule', '--html', '--template-dir', './templates'])
77
```
78

79
## Architecture
80

81
pdoc3 is built around a hierarchical documentation object model:
82

83
- **Doc**: Base class for all documentation objects with common properties (name, module, docstring, etc.)
84
- **Module**: Represents module documentation, handles package traversal and submodule discovery
85
- **Class**: Represents class documentation with inheritance analysis and member organization
86
- **Function**: Represents function/method documentation with signature analysis and parameter handling
87
- **Variable**: Represents variable documentation (module, class, or instance variables)
88
- **External**: Represents external/undocumented identifiers for cross-referencing
89
- **Context**: Global registry mapping identifiers to documentation objects for cross-linking
90

91
The template system uses Mako templates for customizable HTML and text output generation, while the CLI provides both batch processing and interactive development server capabilities.
92

93
## Capabilities
94

95
### Core Documentation API
96

97
Generate documentation programmatically using the main API functions and Module objects. Supports filtering, template customization, and various output formats.
98

99
```python { .api }
100
def html(module_name, docfilter=None, reload=False, skip_errors=False, **kwargs) -> str: ...
101
def text(module_name, docfilter=None, reload=False, skip_errors=False, **kwargs) -> str: ...
102
def import_module(module, reload=False, skip_errors=False) -> ModuleType: ...
103
def reset() -> None: ...
104
def link_inheritance(context=None) -> None: ...
105

106
class Module:
107
    def __init__(self, module, docfilter=None, supermodule=None, context=None, skip_errors=False): ...
108
    def html(self, minify=True, **kwargs) -> str: ...
109
    def text(self, **kwargs) -> str: ...
110
```
111

112
[Core Documentation API](./core-api.md)
113

114
### Documentation Objects
115

116
Work with individual documentation objects to analyze and manipulate code documentation. Includes classes for modules, classes, functions, variables, and external references.
117

118
```python { .api }
119
class Doc:
120
    def __init__(self, name: str, module, obj, docstring: str = ''): ...
121
    def url(self, relative_to=None, link_prefix='', top_ancestor=False) -> str: ...
122

123
class Class(Doc):
124
    def mro(self, only_documented=False) -> List['Class']: ...
125
    def methods(self, include_inherited=True, sort=True) -> List['Function']: ...
126
    def class_variables(self, include_inherited=True, sort=True) -> List['Variable']: ...
127

128
class Function(Doc):
129
    def params(self, annotate=False, link=None) -> List[str]: ...
130
    def return_annotation(self, link=None) -> str: ...
131
```
132

133
[Documentation Objects](./doc-objects.md)
134

135
### Command Line Interface
136

137
Use pdoc3 from the command line to generate documentation, start development servers, and integrate with build systems.
138

139
```python { .api }
140
def main(_args=None) -> None: ...
141

142
class _WebDoc(BaseHTTPRequestHandler):
143
    def do_GET(self): ...
144
    def do_HEAD(self): ...
145
```
146

147
[Command Line Interface](./cli.md)
148

149
### HTML and Markdown Processing
150

151
Process docstrings and generate formatted output with support for multiple docstring formats, LaTeX math, syntax highlighting, and cross-linking.
152

153
```python { .api }
154
def to_html(text, docformat=None, module=None, link=None, latex_math=False) -> str: ...
155
def to_markdown(text, docformat=None, module=None, link=None) -> str: ...
156
def minify_html(html: str) -> str: ...
157
def minify_css(css: str) -> str: ...
158
def glimpse(text: str, max_length=153, paragraph=True) -> str: ...
159
```
160

161
[HTML and Markdown Processing](./html-processing.md)
162

163
## Global Configuration
164

165
```python { .api }
166
# Template system
167
tpl_lookup: TemplateLookup  # Mako template lookup object
168

169
# Documentation override system  
170
__pdoc__: Dict[str, Union[bool, str]]  # Global documentation overrides
171

172
# Context management
173
class Context(dict):
174
    def __init__(self, *args, **kwargs): ...
175

176
# Version information
177
__version__: str  # Package version string
178
```
179

180
## Common Error Handling
181

182
pdoc3 provides several mechanisms for handling errors during documentation generation:
183

184
- **`skip_errors=True`**: Continue processing when encountering unimportable modules
185
- **`Module.ImportWarning`**: Custom warning class for import issues
186
- **`ReferenceWarning`**: Warning for unresolved cross-references
187
- **Template error handling**: Detailed error reporting for template rendering issues
188

189
## Types
190

191
```python { .api }
192
from typing import Dict, List, Optional, Union, Callable, Any, Type, TypeVar
193
from types import ModuleType
194

195
# Type variables
196
T = TypeVar('T', 'Module', 'Class', 'Function', 'Variable')
197

198
# Function signatures
199
DocFilter = Callable[[Doc], bool]
200
LinkFunction = Callable[[Doc], str]
201

202
# Configuration types
203
TemplateConfig = Dict[str, Any]
204
DocMapping = Dict[str, Union[Module, Class, Function, Variable]]
205
```