0
# Documentation Rendering
1

2
Comprehensive rendering capabilities that generate documentation output in various formats including standalone Markdown, MkDocs, Hugo, Docusaurus, and custom Jinja2 templates.
3

4
## Capabilities
5

6
### Markdown Rendering
7

8
Basic Markdown renderer that generates standalone Markdown files with configurable formatting, table of contents, and source linking.
9

10
```python { .api }
11
class MarkdownRenderer(Renderer, SinglePageRenderer, SingleObjectRenderer):
12
    """
13
    Basic Markdown renderer for generating standalone documentation files.
14
    
15
    Attributes:
16
        filename: Output filename (default: None for stdout)
17
        add_source_linker: Include source code links (default: True)  
18
        add_member_class_prefix: Add class prefix to member names (default: True)
19
        render_toc: Generate table of contents (default: False)
20
        toc_maxdepth: Maximum TOC depth (default: 2)
21
        insert_header_anchors: Add anchor links to headers (default: False)
22
        header_level_by_type: Header levels for different object types
23
        code_lang: Language for code blocks (default: "python")
24
        signature_with_def: Include 'def' keyword in signatures (default: False)
25
        signature_class_prefix: Include class name in method signatures (default: False)
26
        signature_function_override: Custom signature formatting function
27
        signature_code_block: Wrap signatures in code blocks (default: True)
28
        source_linker: Source linker instance for generating source links
29
    """
30
    filename: Optional[str]
31
    add_source_linker: bool
32
    add_member_class_prefix: bool
33
    render_toc: bool
34
    toc_maxdepth: int
35
    insert_header_anchors: bool
36
    header_level_by_type: Dict[str, int]
37
    code_lang: str
38
    signature_with_def: bool
39
    signature_class_prefix: bool
40
    signature_function_override: Optional[str]
41
    signature_code_block: bool
42
    source_linker: Optional[SourceLinker]
43
    
44
    def render(self, modules: List[docspec.Module]) -> None:
45
        """
46
        Render modules to Markdown format.
47
        
48
        Args:
49
            modules: List of modules to render
50
        """
51
    
52
    def render_single_page(self, fp: TextIO, modules: List[docspec.Module], page_title: Optional[str] = None) -> None:
53
        """
54
        Render modules to a single page.
55
        
56
        Args:
57
            fp: File object to write to
58
            modules: List of modules to render
59
            page_title: Optional title for the page
60
        """
61
    
62
    def render_object(self, fp: TextIO, obj: docspec.ApiObject, options: Dict[str, Any]) -> None:
63
        """
64
        Render a single API object.
65
        
66
        Args:
67
            fp: File object to write to
68
            obj: API object to render
69
            options: Rendering options
70
        """
71
```
72

73
### MkDocs Rendering
74

75
MkDocs-specific renderer with development server support, automatic navigation generation, and build integration.
76

77
```python { .api }
78
class MkdocsRenderer(Renderer, Server, Builder):
79
    """
80
    MkDocs renderer with development server and build capabilities.
81
    
82
    Attributes:
83
        config_file_path: Path to mkdocs.yml config file (default: "mkdocs.yml")
84
        build_directory: Directory for generated files (default: "docs/")  
85
        site_dir: Directory for built site (default: "site/")
86
        markdown: Nested MarkdownRenderer for content generation
87
    """
88
    config_file_path: str
89
    build_directory: str
90
    site_dir: str
91
    markdown: MarkdownRenderer
92
    
93
    def render(self, modules: List[docspec.Module]) -> None:
94
        """
95
        Render modules for MkDocs.
96
        
97
        Args:
98
            modules: List of modules to render
99
        """
100
    
101
    def build(self, site_dir: str) -> None:
102
        """
103
        Build MkDocs site.
104
        
105
        Args:
106
            site_dir: Directory for build output
107
        """
108
    
109
    def get_server_url(self) -> str:
110
        """
111
        Get development server URL.
112
        
113
        Returns:
114
            URL of the development server
115
        """
116
    
117
    def start_server(self) -> subprocess.Popen:
118
        """
119
        Start MkDocs development server.
120
        
121
        Returns:
122
            Process handle for the server
123
        """
124
```
125

126
### Hugo Rendering
127

128
Hugo-specific renderer with development server support, content organization, and build integration.
129

130
```python { .api }
131
class HugoRenderer(Renderer, Server, Builder):
132
    """
133
    Hugo renderer with development server and build capabilities.
134
    
135
    Attributes:
136
        config_file: Hugo config file name (default: "config.toml")
137
        build_directory: Directory for content files (default: "content/docs/")
138
        site_dir: Directory for built site (default: "public/")
139
        hugo_cmd: Hugo command to use (default: "hugo")
140
        markdown: Nested MarkdownRenderer for content generation
141
    """
142
    config_file: str
143
    build_directory: str
144
    site_dir: str
145
    hugo_cmd: str
146
    markdown: MarkdownRenderer
147
    
148
    def render(self, modules: List[docspec.Module]) -> None:
149
        """
150
        Render modules for Hugo.
151
        
152
        Args:
153
            modules: List of modules to render
154
        """
155
    
156
    def build(self, site_dir: str) -> None:
157
        """
158
        Build Hugo site.
159
        
160
        Args:
161
            site_dir: Directory for build output
162
        """
163
    
164
    def get_server_url(self) -> str:
165
        """
166
        Get development server URL.
167
        
168
        Returns:
169
            URL of the development server
170
        """
171
    
172
    def start_server(self) -> subprocess.Popen:
173
        """
174
        Start Hugo development server.
175
        
176
        Returns:
177
            Process handle for the server
178
        """
179
```
180

181
### Docusaurus Rendering
182

183
Docusaurus-specific renderer with automatic sidebar generation and content organization optimized for React-based documentation sites.
184

185
```python { .api }
186
class DocusaurusRenderer(Renderer):
187
    """
188
    Docusaurus renderer for React-based documentation sites.
189
    
190
    Attributes:
191
        config_file_path: Path to docusaurus.config.js (default: "docusaurus.config.js")
192
        docs_base_path: Base path for documentation files (default: "docs/")
193
        sidebar_top_level_label: Label for top-level sidebar section (default: "API")  
194
        sidebar_top_level_module: Module to use as top-level (default: None)
195
        markdown: Nested MarkdownRenderer for content generation
196
    """
197
    config_file_path: str
198
    docs_base_path: str
199
    sidebar_top_level_label: str
200
    sidebar_top_level_module: Optional[str]
201
    markdown: MarkdownRenderer
202
    
203
    def render(self, modules: List[docspec.Module]) -> None:
204
        """
205
        Render modules for Docusaurus.
206
        
207
        Args:
208
            modules: List of modules to render
209
        """
210
```
211

212
### Jinja2 Rendering
213

214
Template-based renderer using Jinja2 for complete customization of documentation output format and structure.
215

216
```python { .api }
217
class Jinja2Renderer(Renderer):
218
    """
219
    Jinja2 template-based renderer for custom documentation formats.
220
    
221
    Attributes:
222
        loader: Jinja2 loader for template discovery
223
        context: Additional template context variables
224
        template: Template name to render
225
    """
226
    loader: jinja2.BaseLoader
227
    context: Dict[str, Any]
228
    template: str
229
    
230
    def render(self, modules: List[docspec.Module]) -> None:
231
        """
232
        Render modules using Jinja2 templates.
233
        
234
        Args:
235
            modules: List of modules to render
236
        """
237
```
238

239
## Usage Examples
240

241
### Basic Markdown Rendering
242

243
```python
244
from pydoc_markdown import PydocMarkdown
245
from pydoc_markdown.contrib.renderers.markdown import MarkdownRenderer
246

247
# Simple Markdown output
248
renderer = MarkdownRenderer(
249
    filename='api-docs.md',
250
    render_toc=True,
251
    toc_maxdepth=3
252
)
253

254
config = PydocMarkdown(renderer=renderer)
255
modules = config.load_modules()
256
config.process(modules)
257
config.render(modules)
258
```
259

260
### MkDocs Integration
261

262
```python
263
from pydoc_markdown.contrib.renderers.mkdocs import MkdocsRenderer
264
from pydoc_markdown.contrib.renderers.markdown import MarkdownRenderer
265

266
# MkDocs renderer with custom Markdown settings
267
renderer = MkdocsRenderer(
268
    config_file_path='mkdocs.yml',
269
    build_directory='docs/',
270
    markdown=MarkdownRenderer(
271
        render_toc=False,  # MkDocs handles TOC
272
        insert_header_anchors=True
273
    )
274
)
275

276
config = PydocMarkdown(renderer=renderer)
277
```
278

279
### Hugo Integration
280

281
```python
282
from pydoc_markdown.contrib.renderers.hugo import HugoRenderer
283

284
# Hugo renderer with custom configuration
285
renderer = HugoRenderer(
286
    config_file='config.yaml',
287
    build_directory='content/docs/',
288
    site_dir='public/',
289
    hugo_cmd='hugo --minify'
290
)
291

292
config = PydocMarkdown(renderer=renderer)
293
```
294

295
### Development Server
296

297
```python
298
from pydoc_markdown.main import RenderSession
299

300
# Start development server (for MkDocs/Hugo renderers)
301
session = RenderSession(config='pydoc-markdown.yml')
302
config = session.load()
303

304
# This starts the server and watches for changes
305
session.run_server(config, open_browser=True)
306
```
307

308
### Custom Jinja2 Templates
309

310
```python
311
from pydoc_markdown.contrib.renderers.jinja2 import Jinja2Renderer
312
import jinja2
313

314
# Custom template renderer
315
renderer = Jinja2Renderer(
316
    loader=jinja2.FileSystemLoader('templates/'),
317
    template='custom-api.html',
318
    context={'project_name': 'My Project', 'version': '1.0.0'}
319
)
320

321
config = PydocMarkdown(renderer=renderer)
322
```
323

324
## Configuration Examples
325

326
### YAML Configuration
327

328
```yaml
329
# Basic Markdown renderer
330
renderer:
331
  type: markdown
332
  filename: docs/api.md
333
  render_toc: true
334
  toc_maxdepth: 3
335
  insert_header_anchors: true
336
  code_lang: python
337

338
# MkDocs renderer
339
renderer:
340
  type: mkdocs
341
  config_file_path: mkdocs.yml
342
  build_directory: docs/
343
  site_dir: site/
344
  markdown:
345
    render_toc: false
346
    insert_header_anchors: true
347
    signature_code_block: true
348

349
# Hugo renderer  
350
renderer:
351
  type: hugo
352
  config_file: config.toml
353
  build_directory: content/docs/
354
  site_dir: public/
355
  hugo_cmd: hugo --minify
356
  markdown:
357
    render_toc: false
358
    header_level_by_type:
359
      Module: 1
360
      Class: 2
361
      Function: 3
362

363
# Docusaurus renderer
364
renderer:
365
  type: docusaurus
366
  docs_base_path: docs/
367
  sidebar_top_level_label: API Reference
368
  markdown:
369
    render_toc: false
370
    signature_code_block: true
371
```
372

373
### Advanced Markdown Configuration
374

375
```yaml
376
renderer:
377
  type: markdown
378
  filename: api-reference.md
379
  
380
  # Content options
381
  render_toc: true  
382
  toc_maxdepth: 4
383
  insert_header_anchors: true
384
  add_source_linker: true
385
  add_member_class_prefix: false
386
  
387
  # Signature formatting
388
  signature_with_def: false
389
  signature_class_prefix: true  
390
  signature_code_block: true
391
  code_lang: python
392
  
393
  # Header levels for different object types
394
  header_level_by_type:
395
    Module: 1
396
    Class: 2
397
    Function: 3
398
    Method: 4
399
    Variable: 4
400
```
401

402
### Multi-Format Rendering
403

404
You can also use multiple renderers by running pydoc-markdown multiple times with different configurations:
405

406
```bash
407
# Generate Markdown docs
408
pydoc-markdown -c pydoc-markdown-md.yml
409

410
# Generate MkDocs site  
411
pydoc-markdown -c pydoc-markdown-mkdocs.yml
412

413
# Generate Hugo site
414
pydoc-markdown -c pydoc-markdown-hugo.yml
415
```
416

417
## Server and Build Integration
418

419
### Development Workflow
420

421
```bash
422
# Start development server (auto-rebuilds on changes)
423
pydoc-markdown --server
424

425
# Open browser automatically
426
pydoc-markdown --server --open
427

428
# Build production site
429
pydoc-markdown --build
430

431
# Build to custom directory
432
pydoc-markdown --build --site-dir /var/www/docs/
433
```
434

435
### Programmatic Server Control
436

437
```python
438
from pydoc_markdown.main import RenderSession
439

440
session = RenderSession(config='mkdocs-config.yml')
441
config = session.load()
442

443
# Check if renderer supports server
444
if hasattr(config.renderer, 'start_server'):
445
    # Start server process
446
    process = config.renderer.start_server()
447
    print(f"Server running at {config.renderer.get_server_url()}")
448
    
449
    # Server will run until process is terminated
450
    process.wait()
451
```