0
# Documentation Generation
1

2
Generate comprehensive API documentation and create documentation sites from notebooks. The documentation system creates searchable API references, handles cross-references, and integrates with Quarto for website generation.
3

4
## Capabilities
5

6
### Main Documentation Export
7

8
Export notebooks to create comprehensive documentation with automatic API reference generation.
9

10
```python { .api }
11
def nbdev_export():
12
    """
13
    Export notebooks to create documentation.
14
    
15
    Processes notebooks to generate:
16
    - API documentation from docstrings
17
    - Cross-reference links between functions
18
    - Module indices and navigation
19
    - Integration with documentation hosting
20
    """
21
```
22

23
**Usage Example:**
24

25
```python
26
from nbdev.doclinks import nbdev_export
27

28
# Generate documentation from notebooks
29
nbdev_export()
30
```
31

32
### Symbol Documentation Display
33

34
Display formatted documentation for Python objects in notebooks and websites.
35

36
```python { .api }
37
def show_doc(obj, title_level: int = None, doc_string: bool = True, 
38
            name: str = None, disp: bool = True):
39
    """
40
    Display documentation for an object.
41
    
42
    Args:
43
        obj: Python object to document
44
        title_level: Heading level for documentation title
45
        doc_string: Include object's docstring
46
        name: Override default name display
47
        disp: Whether to display the documentation
48
        
49
    Returns:
50
        Formatted documentation display for notebooks and websites
51
    """
52

53
def doc(obj):
54
    """
55
    Get documentation for an object.
56
    
57
    Args:
58
        obj: Python object to get documentation for
59
        
60
    Returns:
61
        Documentation string for the object
62
    """
63
```
64

65
**Usage Examples:**
66

67
```python
68
from nbdev.showdoc import show_doc, doc
69
from nbdev.export import nb_export
70

71
# Show documentation in notebook
72
show_doc(nb_export)
73

74
# Get documentation string
75
doc_string = doc(nb_export)
76
print(doc_string)
77
```
78

79
### Documentation Index Creation
80

81
Create searchable indices and cross-references for documentation.
82

83
```python { .api }
84
def create_index():
85
    """
86
    Create documentation index.
87
    
88
    Generates searchable index of all documented functions, classes,
89
    and modules in the project for navigation and cross-referencing.
90
    """
91

92
class NbdevLookup:
93
    """
94
    Class for looking up documentation links and references.
95
    
96
    Provides functionality to resolve cross-references between
97
    documentation pages and create proper linking structure.
98
    """
99
```
100

101
### Documentation Utilities
102

103
Utility functions for documentation processing and formatting.
104

105
```python { .api }
106
def showdoc_nm(obj):
107
    """
108
    Get showdoc name for an object.
109
    
110
    Args:
111
        obj: Python object
112
        
113
    Returns:
114
        Canonical name for use in documentation systems
115
    """
116

117
def colab_link(nb_path: str):
118
    """
119
    Generate Google Colab links for notebooks.
120
    
121
    Args:
122
        nb_path: Path to notebook file
123
        
124
    Returns:
125
        URL for opening notebook in Google Colab
126
    """
127

128
def patch_name(obj):
129
    """
130
    Get patch-decorated function names.
131
    
132
    Args:
133
        obj: Function object potentially decorated with @patch
134
        
135
    Returns:
136
        Proper name including class prefix for patched methods
137
    """
138
```
139

140
### Notebook Pattern Matching
141

142
Find and process notebooks based on patterns and filters.
143

144
```python { .api }
145
def nbglob(pattern: str = None):
146
    """
147
    Glob patterns for finding notebooks.
148
    
149
    Args:
150
        pattern: Glob pattern for notebook matching
151
        
152
    Returns:
153
        List of notebook paths matching the pattern
154
    """
155

156
def nbglob_cli():
157
    """
158
    Command-line interface for notebook globbing.
159
    
160
    Provides CLI access to notebook pattern matching
161
    for use in scripts and automation.
162
    """
163
```
164

165
## Documentation Renderers
166

167
Multiple renderers for different output formats and environments.
168

169
### Base Renderer
170

171
```python { .api }
172
class ShowDocRenderer:
173
    """
174
    Base renderer for show_doc functionality.
175
    
176
    Provides the foundation for rendering documentation
177
    in different formats and environments.
178
    """
179
```
180

181
### Markdown Renderer
182

183
```python { .api }
184
class BasicMarkdownRenderer(ShowDocRenderer):
185
    """
186
    Markdown renderer for documentation.
187
    
188
    Renders documentation in Markdown format suitable
189
    for static site generators and documentation sites.
190
    """
191
```
192

193
### HTML Renderer
194

195
```python { .api }
196
class BasicHtmlRenderer(ShowDocRenderer):
197
    """
198
    HTML renderer for documentation.
199
    
200
    Renders documentation in HTML format for direct
201
    web display and interactive environments.
202
    """
203
```
204

205
### Documentation Table
206

207
```python { .api }
208
class DocmentTbl:
209
    """
210
    Documentation table class.
211
    
212
    Creates formatted tables for function parameters,
213
    return values, and other documentation elements.
214
    """
215
    
216
    def __init__(self, obj, verbose: bool = True, returns: bool = True):
217
        """
218
        Initialize documentation table.
219
        
220
        Args:
221
            obj: Object to create documentation table for
222
            verbose: Include detailed parameter information
223
            returns: Include return value documentation
224
        """
225
```
226

227
## Documentation Integration
228

229
### Quarto Integration
230

231
nbdev integrates with Quarto for advanced documentation site generation:
232

233
```python
234
from nbdev.quarto import install_quarto, nbdev_sidebar
235

236
# Install Quarto for documentation generation
237
install_quarto()
238

239
# Generate sidebar navigation
240
nbdev_sidebar()
241
```
242

243
### Website Generation
244

245
Create complete documentation websites from notebooks:
246

247
```python
248
from nbdev.doclinks import nbdev_export, create_index
249

250
# Generate documentation
251
nbdev_export()
252

253
# Create searchable index
254
create_index()
255
```
256

257
## Usage Patterns
258

259
### Basic Documentation Workflow
260

261
```python
262
from nbdev.doclinks import nbdev_export
263
from nbdev.showdoc import show_doc
264

265
# In notebook cells - document functions as you write them
266
def my_function(x, y):
267
    """Add two numbers together."""
268
    return x + y
269

270
# Show documentation inline
271
show_doc(my_function)
272

273
# Export to create full documentation site
274
nbdev_export()
275
```
276

277
### Advanced Documentation Features
278

279
```python
280
from nbdev.doclinks import NbdevLookup, create_index
281
from nbdev.showdoc import BasicMarkdownRenderer
282

283
# Create documentation lookup system
284
lookup = NbdevLookup()
285

286
# Use custom renderer
287
renderer = BasicMarkdownRenderer()
288

289
# Create comprehensive index
290
create_index()
291
```
292

293
### Cross-Reference Management
294

295
```python
296
from nbdev.doclinks import patch_name, typs, bset
297

298
# Handle patched method names
299
func_name = patch_name(some_method)
300

301
# Manage type information
302
type_info = typs(some_object)
303

304
# Handle base sets for documentation
305
base_set = bset(collection)
306
```
307

308
## Configuration
309

310
Documentation generation respects configuration settings:
311

312
- `doc_host`: Documentation hosting URL
313
- `doc_baseurl`: Base URL for documentation
314
- `doc_path`: Output directory for documentation
315
- `custom_sidebar`: Use custom sidebar configuration
316
- `title`: Website title for documentation
317

318
**Example:**
319

320
```python
321
from nbdev.config import get_config
322

323
config = get_config()
324
print(f"Docs will be hosted at: {config.doc_host}{config.doc_baseurl}")
325
print(f"Output directory: {config.doc_path}")
326
```