0
# pdoc
1

2
API Documentation for Python Projects with focus on simplicity and automatic HTML generation from docstrings. pdoc auto-generates clean, readable API documentation directly from Python source code by analyzing type annotations, docstrings, and module structures using abstract syntax tree parsing.
3

4
## Package Information
5

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

11
## Core Imports
12

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

17
For main functionality:
18

19
```python
20
from pdoc import pdoc
21
```
22

23
For documentation object access:
24

25
```python
26
from pdoc import doc, extract, render
27
```
28

29
## Basic Usage
30

31
### Command Line Interface
32

33
```python
34
# Generate documentation for a module
35
pdoc your_module
36

37
# Generate documentation for a file
38
pdoc ./my_project.py
39

40
# Save to HTML files
41
pdoc your_module -o ./docs
42

43
# Start development server with live reload
44
pdoc your_module --host localhost --port 8080
45
```
46

47
### Programmatic API
48

49
```python
50
import pdoc
51

52
# Generate documentation for modules
53
html_output = pdoc.pdoc("my_module")  # Returns HTML string
54

55
# Save to directory
56
pdoc.pdoc("my_module", output_directory="./docs")  # Writes HTML files
57

58
# Configure rendering options
59
pdoc.render.configure(
60
    docformat="google",  # Support Google-style docstrings
61
    show_source=True,    # Include source code links
62
    math=True            # Enable math formula rendering
63
)
64
```
65

66
## Architecture
67

68
pdoc follows a modular architecture with clear separation of concerns:
69

70
- **Module Extraction**: Discovers and loads Python modules safely while handling import errors
71
- **Documentation Objects**: Represents Python constructs (modules, classes, functions) as structured objects
72
- **AST Processing**: Analyzes source code using Python's abstract syntax tree for accurate type and signature extraction
73
- **Docstring Processing**: Converts various docstring formats (Markdown, Google, NumPy, reStructuredText) to HTML
74
- **HTML Rendering**: Template-based HTML generation with customizable Jinja2 templates
75
- **Web Server**: Built-in development server with live reloading and automatic regeneration
76

77
## Capabilities
78

79
### Main Documentation Generation
80

81
Core functionality for generating documentation from Python modules using the primary `pdoc()` function with flexible output options.
82

83
```python { .api }
84
def pdoc(*modules: Path | str, output_directory: Path | None = None) -> str | None:
85
    """
86
    Render documentation for modules.
87
    
88
    Parameters:
89
    - modules: Module names or file paths to document
90
    - output_directory: Directory for HTML output (None returns HTML string)
91
    
92
    Returns:
93
    - HTML string if output_directory is None, else None
94
    """
95
```
96

97
[Main API](./main-api.md)
98

99
### Documentation Objects
100

101
Object model for representing Python modules, classes, functions, and variables with their metadata, signatures, and docstrings.
102

103
```python { .api }
104
class Module(Namespace):
105
    """Module documentation object"""
106
    @classmethod
107
    def from_name(cls, module_name: str) -> 'Module': ...
108

109
class Class(Namespace):
110
    """Class documentation object"""
111
    pass
112

113
class Function(Doc):
114
    """Function/method documentation object"""
115
    pass
116

117
class Variable(Doc):
118
    """Variable/attribute documentation object"""
119
    pass
120
```
121

122
[Documentation Objects](./doc-objects.md)
123

124
### Module Extraction and Loading
125

126
Utilities for discovering, loading, and walking Python modules with error handling and import safety.
127

128
```python { .api }
129
def walk_specs(modules: Iterable[Path | str]) -> Iterator[str]: ...
130
def load_module(module_name: str) -> ModuleType: ...
131
def parse_spec(spec: str) -> tuple[str, bool]: ...
132
def walk_packages2(paths: list[str], prefix: str = "") -> Iterator[ModuleInfo]: ...
133
```
134

135
[Module Extraction](./module-extraction.md)
136

137
### HTML Rendering and Templates
138

139
Template-based HTML generation system with customizable Jinja2 templates and rendering configuration options.
140

141
```python { .api }
142
def configure(
143
    docformat: str = "restructuredtext",
144
    show_source: bool = True,
145
    math: bool = False,
146
    mermaid: bool = False,
147
    **kwargs
148
) -> None: ...
149

150
def html_module(module: doc.Module, all_modules: dict[str, doc.Module]) -> str: ...
151
def html_index(all_modules: dict[str, doc.Module]) -> str: ...
152
```
153

154
[HTML Rendering](./html-rendering.md)
155

156
### Docstring Processing
157

158
Multi-format docstring conversion supporting Markdown, Google, NumPy, and reStructuredText styles with cross-reference linking.
159

160
```python { .api }
161
def convert(docstring: str, docformat: str = "restructuredtext") -> str: ...
162
def google(text: str) -> str: ...
163
def numpy(text: str) -> str: ...
164
def rst(text: str) -> str: ...
165
```
166

167
[Docstring Processing](./docstring-processing.md)
168

169
### Web Development Server
170

171
Built-in HTTP server for documentation development with live reloading and automatic regeneration on source changes.
172

173
```python { .api }
174
class DocServer:
175
    """HTTP server for serving documentation with live reload"""
176
    def __init__(self, addr: tuple[str, int], **kwargs): ...
177
    def serve_forever(self): ...
178

179
def open_browser(url: str) -> None: ...
180
```
181

182
[Web Server](./web-server.md)
183

184
### AST Processing and Source Analysis
185

186
Abstract syntax tree processing for extracting Python code structure, type annotations, and source code metadata.
187

188
```python { .api }
189
def parse(obj: Any) -> ast.AST | None: ...
190
def get_source(obj: Any) -> str | None: ...
191
def unparse(tree: ast.AST) -> str: ...
192
def sort_by_source(items: list[Doc]) -> list[Doc]: ...
193
```
194

195
[AST Processing](./ast-processing.md)
196

197
### Search Functionality
198

199
Client-side search index generation for fast documentation search capabilities in rendered HTML output.
200

201
```python { .api }
202
def make_index(all_modules: dict[str, doc.Module]) -> dict: ...
203
def search_index(all_modules: dict[str, doc.Module]) -> str: ...
204
```
205

206
[Search](./search.md)
207

208
### Command Line Interface
209

210
Comprehensive command-line interface for generating documentation with extensive customization options and development server capabilities.
211

212
```python { .api }
213
def cli(args: list[str] | None = None) -> None:
214
    """
215
    Command-line interface entry point.
216
    
217
    Parameters:
218
    - args: Command line arguments (uses sys.argv if None)
219
    
220
    Features:
221
    - Module specification parsing
222
    - Output format selection
223
    - Development server with live reload
224
    - Template and styling customization
225
    """
226

227
def get_dev_version() -> str:
228
    """
229
    Get development version string with git commit information.
230
    
231
    Returns:
232
    - str: Version string with git commit hash if in development
233
    """
234
```
235

236
[CLI Interface](./cli-interface.md)
237

238
## Types
239

240
```python { .api }
241
class Doc:
242
    """Base documentation object"""
243
    name: str
244
    qualname: str
245
    fullname: str
246
    obj: Any
247
    taken_from: tuple[str, str]
248
    
249
class Namespace(Doc):
250
    """Base class for modules and classes"""
251
    members: dict[str, Doc]
252
    
253
class ModuleInfo:
254
    """Module discovery information"""
255
    module_finder: MetaPathFinder
256
    name: str
257
    ispkg: bool
258
```