0
# nbdev
1

2
nbdev is a notebook-driven development platform that enables developers to create high-quality software packages directly from Jupyter notebooks. It provides comprehensive tooling for automatic documentation generation, seamless publishing to PyPI and conda repositories, two-way synchronization between notebooks and plain-text source code, parallel test execution, built-in continuous integration, and git-friendly notebook handling.
3

4
## Package Information
5

6
- **Package Name**: nbdev
7
- **Language**: Python
8
- **Installation**: `pip install nbdev`
9

10
## Core Imports
11

12
```python
13
import nbdev
14
from nbdev import nbdev_export, show_doc
15
```
16

17
Common workflow imports:
18

19
```python
20
from nbdev.config import get_config, nbdev_create_config
21
from nbdev.export import nb_export
22
from nbdev.test import nbdev_test
23
from nbdev.clean import nbdev_clean
24
```
25

26
## Basic Usage
27

28
```python
29
import nbdev
30
from nbdev.config import get_config, nbdev_create_config
31
from nbdev.export import nb_export
32

33
# Create a new nbdev project
34
nbdev_create_config()
35

36
# Get current configuration
37
config = get_config()
38
print(f"Project: {config.lib_name}")
39
print(f"Version: {config.version}")
40

41
# Export notebooks to Python modules
42
nb_export()
43
```
44

45
## Architecture
46

47
nbdev is built around several key architectural components:
48

49
- **Configuration System**: Centralized settings management through `settings.ini` files
50
- **Notebook Processing Pipeline**: Extensible system for transforming notebook cells
51
- **Export Engine**: Converts notebook cells to Python modules with proper structure
52
- **Documentation Generator**: Automatic API documentation from notebook content
53
- **Testing Framework**: Execute test cells in parallel across notebooks  
54
- **Git Integration**: Handles notebook metadata and merge conflicts
55
- **CLI Tools**: Command-line interface for all major operations
56

57
The processing pipeline uses a processor pattern where notebooks pass through configurable stages (processors) that can transform, validate, or extract information from cells.
58

59
## Capabilities
60

61
### Project Configuration
62

63
Project setup, configuration management, and bootstrapping functionality for new nbdev projects.
64

65
```python { .api }
66
def nbdev_create_config(
67
    repo: str = None,
68
    branch: str = None,
69
    user: str = None,
70
    author: str = None,
71
    author_email: str = None,
72
    description: str = None,
73
    path: str = '.',
74
    cfg_name: str = 'settings.ini',
75
    **kwargs
76
): ...
77
def get_config(cfg_name: str = 'settings.ini', path=None): ...
78
def config_key(c, default=None, path=True, missing_ok=None): ...  # Deprecated
79
def is_nbdev() -> bool: ...
80
```
81

82
[Configuration](./configuration.md)
83

84
### Notebook Export
85

86
Convert Jupyter notebook cells to Python modules with proper imports, documentation, and structure.
87

88
```python { .api }
89
def nb_export(
90
    nbname: str,
91
    lib_path: str = None,
92
    procs=None,
93
    name: str = None,
94
    mod_maker=ModuleMaker,
95
    debug: bool = False,
96
    solo_nb: bool = False
97
): ...
98
def black_format(cell, force: bool = False): ...
99
class ExportModuleProc: ...
100
```
101

102
[Export](./export.md)
103

104
### Documentation Generation
105

106
Generate comprehensive API documentation and create documentation sites from notebooks.
107

108
```python { .api }
109
def nbdev_export(path: str = None, procs=["black_format"], **kwargs): ...
110
def show_doc(sym, renderer=None, name: str = None, title_level: int = 3): ...
111
def create_index(url, pre=None): ...
112
class NbdevLookup(strip_libs=None, incl_libs=None, skip_mods=None, ns=None): ...
113
```
114

115
[Documentation](./documentation.md)
116

117
### Testing Framework
118

119
Run tests defined in notebook cells across your project in parallel.
120

121
```python { .api }
122
def nbdev_test(
123
    path: str = None,
124
    flags: str = '',
125
    n_workers: int = None,
126
    timing: bool = False,
127
    do_print: bool = False,
128
    pause: float = 0.01,
129
    ignore_fname: str = '.notest',
130
    **kwargs
131
): ...
132
def test_nb(
133
    fn,
134
    skip_flags=None,
135
    force_flags=None,
136
    do_print: bool = False,
137
    showerr: bool = True,
138
    basepath=None
139
): ...
140
```
141

142
[Testing](./testing.md)
143

144
### Notebook Cleaning
145

146
Clean notebook metadata, outputs, and configure git integration for notebooks.
147

148
```python { .api }
149
def nbdev_clean(
150
    fname: str = None,
151
    clear_all: bool = False,
152
    disp: bool = False,
153
    stdin: bool = False
154
): ...
155
def clean_nb(
156
    nb,
157
    clear_all: bool = False,
158
    allowed_metadata_keys: list = None,
159
    allowed_cell_metadata_keys: list = None,
160
    clean_ids: bool = True
161
): ...
162
def nbdev_trust(fname: str = None, force_all: bool = False): ...
163
def nbdev_install_hooks(): ...
164
```
165

166
[Cleaning](./cleaning.md)
167

168
### Code Synchronization
169

170
Synchronize between notebooks and plain Python source code for IDE compatibility.
171

172
```python { .api }
173
def nbdev_update(fname: str = None): ...
174
def absolute_import(name, fname, level): ...
175
```
176

177
[Synchronization](./synchronization.md)
178

179
### Git Integration
180

181
Handle git merge conflicts and notebook-specific version control concerns.
182

183
```python { .api }
184
def nbdev_merge(base: str, ours: str, theirs: str, path: str): ...
185
def nbdev_fix(
186
    nbname: str,
187
    outname: str = None,
188
    nobackup: bool = True,
189
    theirs: bool = False,
190
    noprint: bool = False
191
): ...
192
def unpatch(s: str): ...
193
```
194

195
[Git Integration](./git-integration.md)
196

197
### Release Management
198

199
Automated publishing to PyPI, GitHub releases, and changelog generation.
200

201
```python { .api }
202
class Release(owner=None, repo=None, token=None, **groups): ...
203
def release_git(token: str = None): ...
204
def release_gh(token: str = None): ...
205
def changelog(debug: bool = False, repo: str = None): ...
206
```
207

208
[Release Management](./release-management.md)
209

210
### Development Tools
211

212
Development server, project migration, and various utility functions.
213

214
```python { .api }
215
def nbdev_new(**kwargs): ...
216
def nbdev_migrate(path: str = None, no_skip: bool = False): ...
217
def proc_nbs(
218
    path: str = '',
219
    n_workers: int = None,
220
    force: bool = False,
221
    file_glob: str = '',
222
    file_re: str = '',
223
    **kwargs
224
): ...
225
```
226

227
[Development Tools](./development-tools.md)
228

229
## Command Line Interface
230

231
nbdev provides comprehensive CLI commands:
232

233
```bash
234
# Create new project
235
nbdev_new
236

237
# Export notebooks to modules  
238
nbdev_export
239

240
# Run tests
241
nbdev_test
242

243
# Clean notebooks
244
nbdev_clean
245

246
# Install git hooks
247
nbdev_install_hooks
248

249
# Update from source
250
nbdev_update
251

252
# Merge conflicts
253
nbdev_merge
254

255
# Trust notebooks
256
nbdev_trust
257
```