0
# Development Tools
1

2
Development server, project migration, and various utility functions for nbdev development workflow. These tools support the day-to-day development process and help maintain nbdev projects.
3

4
## Capabilities
5

6
### Project Creation
7

8
Create new nbdev projects with proper structure and configuration.
9

10
```python { .api }
11
def nbdev_new(name: str = None, lib_path: str = None, 
12
              git_url: str = None, branch: str = 'main',
13
              author: str = None, author_email: str = None,
14
              description: str = None, path: str = '.'):
15
    """
16
    Create new nbdev project.
17
    
18
    Args:
19
        name: Project name
20
        lib_path: Library path (defaults to name with underscores)
21
        git_url: Git repository URL
22
        branch: Default git branch
23
        author: Package author name
24
        author_email: Author email address
25
        description: Project description
26
        path: Directory to create project in
27
        
28
    Creates complete nbdev project structure with:
29
    - settings.ini configuration
30
    - Initial notebook files
31
    - Python package structure
32
    - Git repository initialization
33
    - GitHub Actions workflows
34
    """
35
```
36

37
**Usage Example:**
38

39
```python
40
from nbdev.cli import nbdev_new
41

42
# Create new project interactively
43
nbdev_new()
44

45
# Create project with specific parameters
46
nbdev_new(
47
    name='my-awesome-lib',
48
    author='Your Name',
49
    author_email='you@example.com',
50
    description='An awesome Python library'
51
)
52
```
53

54
### Project Migration
55

56
Migrate existing nbdev projects to newer versions.
57

58
```python { .api }
59
def nbdev_migrate():
60
    """
61
    Migrate nbdev project to current version.
62
    
63
    Updates project structure, configuration files, and notebook
64
    format to be compatible with the current version of nbdev.
65
    Handles breaking changes and deprecated features.
66
    """
67
```
68

69
**Usage Example:**
70

71
```python
72
from nbdev.migrate import nbdev_migrate
73

74
# Migrate current project
75
nbdev_migrate()
76
```
77

78
### Development Server
79

80
Serve notebooks and documentation for development.
81

82
```python { .api }  
83
def proc_nbs():
84
    """
85
    Process notebooks for development server.
86
    
87
    Prepares notebooks for serving by processing them through
88
    the nbdev pipeline and making them available for live preview
89
    and development.
90
    """
91
```
92

93
### Notebook Filtering
94

95
Filter and process notebook content for various purposes.
96

97
```python { .api }
98
def nbdev_filter():
99
    """
100
    Filter notebook content.
101
    
102
    Processes notebook cells through filters to remove or modify
103
    content based on configuration and directives. Used for
104
    preparing notebooks for different environments or outputs.
105
    """
106
```
107

108
### File Operations
109

110
Extract and handle various file formats in nbdev workflows.
111

112
```python { .api }
113
def extract_tgz(fname: str, dest: str = '.'):
114
    """
115
    Extract tar.gz files.
116
    
117
    Args:
118
        fname: Path to tar.gz file
119
        dest: Destination directory for extraction
120
        
121
    Utility for extracting compressed archives, commonly used
122
    in nbdev project templates and distribution.
123
    """
124
```
125

126
### License Management
127

128
Update license information across project files.
129

130
```python { .api }
131
def nbdev_update_license():
132
    """
133
    Update license information in project files.
134
    
135
    Updates license headers, copyright notices, and license
136
    files throughout the project based on settings.ini
137
    configuration.
138
    """
139
```
140

141
### Export Monitoring
142

143
Watch for changes and automatically export notebooks.
144

145
```python { .api }
146
def watch_export():
147
    """
148
    Watch notebooks and automatically export on changes.
149
    
150
    Monitors notebook files for changes and automatically
151
    runs export process when modifications are detected.
152
    Useful for development workflows with continuous export.
153
    """
154
```
155

156
### CLI Help System
157

158
Enhanced help system for command-line tools.
159

160
```python { .api }
161
def chelp(func):
162
    """
163
    CLI help system.
164
    
165
    Args:
166
        func: Function to provide help for
167
        
168
    Enhanced help display for nbdev command-line functions
169
    with better formatting and examples.
170
    """
171
```
172

173
## Command Mapping
174

175
```python { .api }
176
mapping: dict
177
```
178
Dictionary mapping CLI command names to their corresponding functions.
179

180
## Development Workflow Tools
181

182
### Watch and Export Workflow
183

184
```python
185
from nbdev.cli import watch_export
186
from nbdev.export import nb_export
187

188
# Start watching for changes
189
print("Starting watch mode - notebooks will auto-export on changes")
190
watch_export()
191
# This runs continuously, exporting notebooks when they change
192
```
193

194
### Project Maintenance
195

196
```python
197
from nbdev.cli import nbdev_update_license, nbdev_filter
198
from nbdev.migrate import nbdev_migrate
199

200
def maintain_project():
201
    """Maintain and update nbdev project."""
202
    
203
    print("1. Migrating to latest nbdev version...")
204
    nbdev_migrate()
205
    
206
    print("2. Updating license information...")
207
    nbdev_update_license()
208
    
209
    print("3. Filtering notebooks...")
210
    nbdev_filter()
211
    
212
    print("✓ Project maintenance completed")
213

214
maintain_project()
215
```
216

217
### Development Setup
218

219
```python
220
from nbdev.cli import nbdev_new
221
from nbdev.clean import nbdev_install_hooks
222
from nbdev.config import get_config
223

224
def setup_development_environment(project_name: str):
225
    """Set up complete development environment."""
226
    
227
    # Create new project
228
    nbdev_new(name=project_name)
229
    
230
    # Install git hooks
231
    nbdev_install_hooks()
232
    
233
    # Verify setup
234
    config = get_config()
235
    print(f"✓ Development environment ready for {config.lib_name}")
236
    print(f"  Notebooks: {config.nbs_path}")
237
    print(f"  Library: {config.lib_path}")
238
    print(f"  Documentation: {config.doc_path}")
239

240
setup_development_environment("my-new-project")
241
```
242

243
## Advanced Development Features
244

245
### Custom Filters
246

247
```python
248
from nbdev.cli import nbdev_filter
249
from nbdev.process import NBProcessor
250

251
# Create custom notebook processing
252
def custom_development_workflow():
253
    """Custom development workflow with filtering."""
254
    
255
    # Filter notebooks for development
256
    nbdev_filter()
257
    
258
    # Additional custom processing could go here
259
    print("Custom development processing completed")
260

261
custom_development_workflow()
262
```
263

264
### Automated Project Updates
265

266
```python
267
from nbdev.migrate import nbdev_migrate
268
from nbdev.cli import nbdev_update_license
269
from nbdev.config import update_version
270

271
def update_project_to_latest():
272
    """Update project to latest standards and version."""
273
    
274
    # Migrate project structure
275
    nbdev_migrate()
276
    
277
    # Update licenses
278
    nbdev_update_license() 
279
    
280
    # Could add version bumping
281
    # update_version("1.1.0")
282
    
283
    print("Project updated to latest nbdev standards")
284

285
update_project_to_latest()
286
```
287

288
### Development Server Integration
289

290
```python
291
from nbdev.serve import proc_nbs
292
from nbdev.export import nb_export
293

294
def start_development_server():
295
    """Start development server with live reload."""
296
    
297
    # Process notebooks for serving
298
    proc_nbs()
299
    
300
    # Set up continuous export
301
    print("Development server ready")
302
    print("Notebooks will be processed for live preview")
303

304
start_development_server()
305
```
306

307
## Integration with Other Tools
308

309
### IDE Integration
310

311
```python
312
from nbdev.cli import watch_export
313
from nbdev.sync import nbdev_update
314

315
def ide_friendly_workflow():
316
    """Set up IDE-friendly development workflow."""
317
    
318
    # Start auto-export for IDE compatibility
319
    print("Starting auto-export for IDE integration...")
320
    
321
    # In practice, you'd run this in background
322
    # watch_export()
323
    
324
    print("IDE workflow ready:")
325
    print("- Edit notebooks → Auto-export to .py")
326
    print("- Edit .py files → Run nbdev_update()")
327

328
ide_friendly_workflow()
329
```
330

331
### CI/CD Integration
332

333
```python
334
from nbdev.cli import nbdev_filter, extract_tgz
335
from nbdev.test import nbdev_test
336

337
def ci_cd_preparation():
338
    """Prepare project for CI/CD pipelines."""
339
    
340
    # Filter notebooks for CI
341
    nbdev_filter()
342
    
343
    # Run tests to ensure everything works
344
    if nbdev_test():
345
        print("✓ Project ready for CI/CD")
346
    else:
347
        print("❌ Tests failed - fix before deploying")
348

349
ci_cd_preparation()
350
```
351

352
## Utility Functions
353

354
### File Handling
355

356
```python
357
from nbdev.cli import extract_tgz
358

359
# Extract project templates or distributions
360
extract_tgz('project-template.tar.gz', 'new-project/')
361
```
362

363
### Help and Documentation
364

365
```python
366
from nbdev.cli import chelp, mapping
367

368
# Get help for specific function
369
chelp(nb_export)
370

371
# See all available CLI commands
372
print("Available CLI commands:")
373
for cmd, func in mapping.items():
374
    print(f"  {cmd}: {func.__doc__.split('.')[0] if func.__doc__ else 'No description'}")
375
```
376

377
**Complete Development Tools Example:**
378

379
```python
380
from nbdev.cli import (nbdev_new, nbdev_filter, watch_export, 
381
                       nbdev_update_license, extract_tgz, chelp)
382
from nbdev.migrate import nbdev_migrate
383
from nbdev.serve import proc_nbs
384

385
def complete_development_setup(project_name: str):
386
    """Complete development environment setup."""
387
    
388
    print(f"Setting up development environment for {project_name}")
389
    
390
    # 1. Create new project
391
    print("1. Creating new project...")
392
    nbdev_new(name=project_name)
393
    
394
    # 2. Set up development tools
395
    print("2. Setting up development tools...")
396
    proc_nbs()  # Prepare for development server
397
    
398
    # 3. Configure project
399
    print("3. Configuring project...")
400
    nbdev_update_license()  # Ensure licenses are correct
401
    
402
    # 4. Start development workflow
403
    print("4. Development environment ready!")
404
    print(f"   Project: {project_name}")
405
    print("   Use 'watch_export()' for auto-export")
406
    print("   Use 'nbdev_migrate()' to update later")
407
    
408
    return True
409

410
# Set up new development environment
411
complete_development_setup("awesome-ml-lib")
412
```