0
# HTML Rendering and Templates
1

2
Template-based HTML generation system with customizable Jinja2 templates and rendering configuration options. Transforms documentation objects into beautiful, navigable HTML output with customizable styling and layout.
3

4
## Capabilities
5

6
### Rendering Configuration
7

8
Configure global rendering options for all documentation generation.
9

10
```python { .api }
11
def configure(
12
    *,
13
    docformat: Literal["markdown", "google", "numpy", "restructuredtext"] = "restructuredtext",
14
    include_undocumented: bool = True,
15
    edit_url_map: Mapping[str, str] | None = None,
16
    favicon: str | None = None,
17
    footer_text: str = "",
18
    logo: str | None = None,
19
    logo_link: str | None = None,
20
    math: bool = False,
21
    mermaid: bool = False,
22
    search: bool = True,
23
    show_source: bool = True,
24
    template_directory: Path | None = None
25
) -> None:
26
    """
27
    Configure global rendering options for HTML generation.
28
    
29
    Parameters:
30
    - docformat: Docstring format ("markdown", "restructuredtext", "google", "numpy")
31
    - include_undocumented: bool - Include members without docstrings
32
    - edit_url_map: Mapping[str, str] | None - Module name to URL prefix mapping for "Edit on GitHub" links
33
    - favicon: str | None - Path/URL for favicon image
34
    - footer_text: str - Additional text for navigation footer
35
    - logo: str | None - URL to project logo image
36
    - logo_link: str | None - URL the logo should link to
37
    - math: bool - Enable LaTeX math formula rendering via MathJax
38
    - mermaid: bool - Enable Mermaid diagram rendering
39
    - search: bool - Enable search functionality and index building
40
    - show_source: bool - Include "View Source" links in output
41
    - template_directory: Path | None - Custom template directory path
42
    
43
    Effects:
44
    - Sets global options for all subsequent rendering calls
45
    - Configures template engine and processing pipeline
46
    """
47
```
48

49
### Module HTML Generation
50

51
Generate complete HTML documentation for individual modules.
52

53
```python { .api }
54
def html_module(module: doc.Module, all_modules: Mapping[str, doc.Module], mtime: str | None = None) -> str:
55
    """
56
    Render HTML documentation for a single module.
57
    
58
    Parameters:
59
    - module: doc.Module - Module documentation object to render
60
    - all_modules: Mapping[str, doc.Module] - All modules for cross-linking
61
    - mtime: str | None - Include live-reloading JavaScript if provided
62
    
63
    Returns:
64
    - str: Complete HTML document for the module
65
    
66
    Features:
67
    - Cross-module linking and navigation
68
    - Syntax highlighting for code examples
69
    - Responsive design with mobile support
70
    - Customizable via Jinja2 templates
71
    """
72
```
73

74
### Index Page Generation
75

76
Create index pages for multi-module documentation sets.
77

78
```python { .api }
79
def html_index(all_modules: dict[str, doc.Module]) -> str:
80
    """
81
    Generate HTML index page for multiple modules.
82
    
83
    Parameters:
84
    - all_modules: dict[str, doc.Module] - All documented modules
85
    
86
    Returns:
87
    - str: HTML index page content
88
    
89
    Features:
90
    - Module hierarchy navigation
91
    - Search integration
92
    - Overview of all documented modules
93
    """
94
```
95

96
### Error Page Generation
97

98
Generate user-friendly error pages for documentation failures.
99

100
```python { .api }
101
def html_error(
102
    error: Exception,
103
    traceback_str: str,
104
    module_name: str = ""
105
) -> str:
106
    """
107
    Generate HTML error page for documentation failures.
108
    
109
    Parameters:
110
    - error: Exception - The error that occurred
111
    - traceback_str: str - Full traceback information
112
    - module_name: str - Name of module that failed (if applicable)
113
    
114
    Returns:
115
    - str: HTML error page with debugging information
116
    """
117
```
118

119
### Search Index Generation
120

121
Create JavaScript search indices for client-side documentation search.
122

123
```python { .api }
124
def search_index(all_modules: dict[str, doc.Module]) -> str:
125
    """
126
    Generate JavaScript search index for client-side search.
127
    
128
    Parameters:
129
    - all_modules: dict[str, doc.Module] - All modules to index
130
    
131
    Returns:
132
    - str: JavaScript code containing search index data
133
    
134
    Features:
135
    - Full-text search of docstrings and signatures
136
    - Identifier-based search with autocomplete
137
    - Fast client-side search without server requests
138
    """
139
```
140

141
### Debug Representation
142

143
Generate text representations of modules for debugging.
144

145
```python { .api }
146
def repr_module(module: doc.Module) -> str:
147
    """
148
    Generate text representation of module for debugging.
149
    
150
    Parameters:
151
    - module: doc.Module - Module to represent
152
    
153
    Returns:
154
    - str: Text representation showing module structure
155
    """
156
```
157

158
## Usage Examples
159

160
### Basic HTML Generation
161

162
```python
163
from pdoc import render, doc
164

165
# Configure rendering
166
render.configure(
167
    docformat="google",
168
    show_source=True,
169
    math=True
170
)
171

172
# Generate HTML for module
173
module_obj = doc.Module.from_name("my_package")
174
all_modules = {"my_package": module_obj}
175

176
# Render individual module
177
html_content = render.html_module(module_obj, all_modules)
178

179
# Generate index page
180
index_html = render.html_index(all_modules)
181
```
182

183
### Custom Template Configuration
184

185
```python
186
from pdoc import render
187
from pathlib import Path
188

189
# Use custom templates
190
render.configure(
191
    template_directory="./custom_templates",
192
    show_source=False,
193
    math=True,
194
    mermaid=True,
195
    # Custom variables available in templates
196
    project_name="My Project",
197
    project_version="1.0.0"
198
)
199
```
200

201
### Multi-Module Documentation Generation
202

203
```python
204
from pdoc import render, doc
205
from pathlib import Path
206

207
# Load multiple related modules
208
modules = {}
209
module_names = ["core", "utils", "plugins"]
210

211
for name in module_names:
212
    modules[name] = doc.Module.from_name(f"my_project.{name}")
213

214
# Configure for production
215
render.configure(
216
    docformat="numpy",
217
    show_source=True,
218
    math=True,
219
    mermaid=True
220
)
221

222
# Generate all HTML files
223
output_dir = Path("./docs")
224
output_dir.mkdir(exist_ok=True)
225

226
# Render each module
227
for module_name, module_obj in modules.items():
228
    html = render.html_module(module_obj, modules)
229
    (output_dir / f"{module_name}.html").write_text(html)
230

231
# Generate index and search
232
index_html = render.html_index(modules)
233
(output_dir / "index.html").write_text(index_html)
234

235
search_js = render.search_index(modules)
236
(output_dir / "search.js").write_text(search_js)
237
```
238

239
### Error Handling
240

241
```python
242
from pdoc import render, doc
243
import traceback
244

245
def safe_render_module(module_name: str) -> str:
246
    """Safely render module with error handling"""
247
    try:
248
        module_obj = doc.Module.from_name(module_name)
249
        return render.html_module(module_obj, {module_name: module_obj})
250
    except Exception as e:
251
        # Generate error page
252
        tb = traceback.format_exc()
253
        return render.html_error(e, tb, module_name)
254

255
# Usage
256
html_output = safe_render_module("potentially_problematic_module")
257
```
258

259
### Advanced Configuration
260

261
```python
262
from pdoc import render
263

264
# Comprehensive configuration
265
render.configure(
266
    # Docstring processing
267
    docformat="restructuredtext",
268
    
269
    # Source code integration
270
    show_source=True,
271
    
272
    # Enhanced features
273
    math=True,           # LaTeX math rendering
274
    mermaid=True,        # Diagram support
275
    
276
    # Template customization
277
    template_directory="./templates",
278
    
279
    # Custom CSS and styling
280
    custom_css="body { font-family: 'Helvetica'; }",
281
    
282
    # Logo and branding
283
    logo_url="https://example.com/logo.png",
284
    project_name="My API Documentation",
285
    
286
    # Navigation options
287
    sort_identifiers=True,
288
    show_inherited_members=True
289
)
290
```
291

292
### Development vs Production
293

294
```python
295
from pdoc import render
296

297
def configure_for_development():
298
    """Configure for development with debugging features"""
299
    render.configure(
300
        docformat="markdown",
301
        show_source=True,
302
        math=False,
303
        mermaid=False,
304
        # Show all internal details
305
        show_private_members=True
306
    )
307

308
def configure_for_production():
309
    """Configure for production with optimized output"""
310
    render.configure(
311
        docformat="google",
312
        show_source=False,
313
        math=True,
314
        mermaid=True,
315
        # Clean public API only
316
        show_private_members=False,
317
        minify_html=True
318
    )
319
```
320

321
## Template Customization
322

323
### Custom Template Structure
324

325
```python
326
# Directory structure for custom templates:
327
# templates/
328
# ├── module.html.jinja2      # Main module template
329
# ├── index.html.jinja2       # Index page template
330
# ├── frame.html.jinja2       # HTML frame/layout
331
# └── resources/
332
#     ├── theme.css           # Custom CSS
333
#     └── custom.js           # Custom JavaScript
334

335
from pdoc import render
336

337
render.configure(template_directory="./templates")
338
```
339

340
### Template Variables
341

342
Common template variables available in Jinja2 templates:
343

344
- `module`: Current module documentation object
345
- `all_modules`: Dictionary of all modules for cross-linking
346
- `config`: Rendering configuration options
347
- `project_name`: Custom project name
348
- `show_source`: Whether to show source links
349
- `math`: Whether math rendering is enabled