0
# Main Documentation Generation API
1

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

4
## Capabilities
5

6
### Primary Documentation Function
7

8
The main entry point for generating documentation from Python modules, supporting both HTML string output and file-based output to directories.
9

10
```python { .api }
11
def pdoc(*modules: Path | str, output_directory: Path | None = None) -> str | None:
12
    """
13
    Render the documentation for a list of modules.
14

15
    Parameters:
16
    - modules: Module names (str) or file paths (Path) to document
17
    - output_directory: Directory path for HTML output. If None, returns HTML string for first module
18

19
    Returns:
20
    - str: HTML documentation for first module if output_directory is None
21
    - None: if output_directory is specified (writes files to disk)
22
    
23
    Notes:
24
    - Rendering options configured via pdoc.render.configure()
25
    - Creates index.html and search.js when output_directory specified
26
    - All specified modules documented together for cross-linking
27
    """
28
```
29

30
### Usage Examples
31

32
Generate HTML string for single module:
33

34
```python
35
import pdoc
36

37
# Get HTML documentation as string
38
html_docs = pdoc.pdoc("my_package")
39
print(html_docs)  # HTML content for my_package
40
```
41

42
Save documentation to files:
43

44
```python
45
import pdoc
46
from pathlib import Path
47

48
# Write HTML files to docs directory
49
pdoc.pdoc("my_package", "subpackage", output_directory=Path("./docs"))
50
# Creates: docs/my_package.html, docs/subpackage/*.html, docs/index.html, docs/search.js
51
```
52

53
Configure rendering before generation:
54

55
```python
56
import pdoc
57

58
# Configure rendering options
59
pdoc.render.configure(
60
    docformat="google",
61
    show_source=True,
62
    math=True,
63
    mermaid=True
64
)
65

66
# Generate with custom settings
67
pdoc.pdoc("my_package", output_directory=Path("./api-docs"))
68
```
69

70
### Module Access
71

72
Direct access to pdoc's sub-modules for advanced usage.
73

74
```python { .api }
75
from pdoc import doc, extract, render
76
```
77

78
The main pdoc module exposes three key sub-modules:
79
- `doc`: Documentation object model
80
- `extract`: Module loading and discovery  
81
- `render`: HTML template rendering
82

83
## Integration Patterns
84

85
### Custom Processing Pipeline
86

87
```python
88
import pdoc
89

90
# Configure rendering options
91
pdoc.render.configure(
92
    docformat="google",
93
    show_source=True,
94
    template_directory="./custom_templates"
95
)
96

97
# Process multiple related packages
98
modules = ["core_package", "extensions", "utils"]
99
pdoc.pdoc(*modules, output_directory="./complete_docs")
100
```
101

102
### Web Development Workflow
103

104
```python
105
import pdoc
106
from pathlib import Path
107

108
def generate_docs():
109
    """Generate documentation for development"""
110
    pdoc.render.configure(
111
        docformat="markdown",
112
        show_source=True,
113
        math=True
114
    )
115
    
116
    return pdoc.pdoc("my_project")  # Returns HTML for preview
117

118
# Use with web framework
119
html_content = generate_docs()
120
```