0
# Project Configuration
1

2
Project setup, configuration management, and bootstrapping functionality for new nbdev projects. The configuration system uses `settings.ini` files to manage project settings and supports both project-level and global configuration.
3

4
## Capabilities
5

6
### Project Creation
7

8
Create and initialize configuration for new nbdev projects with sensible defaults.
9

10
```python { .api }
11
def nbdev_create_config(
12
    repo: str = None,
13
    branch: str = None,
14
    user: str = None,
15
    author: str = None,
16
    author_email: str = None,
17
    description: str = None,
18
    path: str = '.',
19
    cfg_name: str = 'settings.ini',
20
    **kwargs
21
):
22
    """
23
    Create configuration for new nbdev project.
24
    
25
    Creates a settings.ini file with default values for lib_name, version,
26
    description, and other project settings. Prompts user for required information
27
    and attempts to infer settings from git repository.
28
    """
29
```
30

31
**Usage Example:**
32

33
```python
34
from nbdev.config import nbdev_create_config
35

36
# Create new project configuration
37
nbdev_create_config()
38
# This will create settings.ini with project defaults
39
```
40

41
### Configuration Access
42

43
Access and query current project configuration settings.
44

45
```python { .api }
46
def get_config():
47
    """
48
    Get current configuration settings.
49
    
50
    Returns:
51
        Config object with all project settings loaded from settings.ini
52
        
53
    Raises:
54
        FileNotFoundError: If no settings.ini found in current directory or parents
55
    """
56

57
def config_key(key: str):
58
    """
59
    Get specific configuration value by key.
60
    
61
    Args:
62
        key: Configuration key to retrieve
63
        
64
    Returns:
65
        Configuration value for the specified key
66
    """
67

68
def is_nbdev() -> bool:
69
    """
70
    Check if current directory is an nbdev project.
71
    
72
    Returns:
73
        True if settings.ini exists and contains nbdev configuration
74
    """
75
```
76

77
**Usage Examples:**
78

79
```python
80
from nbdev.config import get_config, config_key, is_nbdev
81

82
# Check if current directory is nbdev project
83
if is_nbdev():
84
    # Get full configuration
85
    config = get_config()
86
    print(f"Library: {config.lib_name}")
87
    print(f"Version: {config.version}")
88
    print(f"Description: {config.description}")
89
    
90
    # Get specific configuration values
91
    lib_path = config_key('lib_path')
92
    doc_path = config_key('doc_path')
93
```
94

95
### Project Structure
96

97
Create output directories and project structure based on configuration.
98

99
```python { .api }
100
def create_output():
101
    """
102
    Create output directories based on configuration.
103
    
104
    Creates lib_path and doc_path directories if they don't exist,
105
    based on current project configuration settings.
106
    """
107

108
def add_init():
109
    """
110
    Add __init__.py files to package directories.
111
    
112
    Ensures proper Python package structure by adding __init__.py files
113
    to all subdirectories in the library path.
114
    """
115
```
116

117
### Version Management
118

119
Update and manage project version information across multiple files.
120

121
```python { .api }
122
def update_version(version: str):
123
    """
124
    Update package version across project files.
125
    
126
    Args:
127
        version: New version string (e.g., "1.2.3")
128
        
129
    Updates version in:
130
    - settings.ini
131
    - __init__.py (if put_version_in_init is True)
132
    - pyproject.toml (if update_pyproject is True)
133
    """
134

135
def update_proj():
136
    """
137
    Update project configuration and dependencies.
138
    
139
    Updates pyproject.toml with current settings and ensures
140
    project metadata is consistent across configuration files.
141
    """
142
```
143

144
### Source Code Display
145

146
Display source code of objects for debugging and exploration.
147

148
```python { .api }
149
def show_src(obj):
150
    """
151
    Show source code of an object.
152
    
153
    Args:
154
        obj: Python object to display source for
155
        
156
    Returns:
157
        Formatted source code display
158
    """
159
```
160

161
### File Operations
162

163
Write notebook cells to files with proper formatting and structure.
164

165
```python { .api }
166
def write_cells(cells, path):
167
    """
168
    Write notebook cells to a file.
169
    
170
    Args:
171
        cells: List of notebook cells to write
172
        path: Output file path
173
        
174
    Writes cells to the specified path with proper Python formatting,
175
    imports, and structure.
176
    """
177
```
178

179
## Configuration Templates
180

181
```python { .api }
182
pyproj_tmpl: str
183
```
184

185
Template string for generating pyproject.toml files with correct project structure and dependencies.
186

187
## Configuration Keys
188

189
Common configuration keys available through `config_key()`:
190

191
- `lib_name`: Package name
192
- `lib_path`: Path to package source code  
193
- `version`: Package version
194
- `description`: Package description
195
- `author`: Package author
196
- `author_email`: Author email address
197
- `copyright`: Copyright notice
198
- `license`: License type
199
- `git_url`: Git repository URL
200
- `doc_host`: Documentation host URL
201
- `doc_baseurl`: Documentation base URL
202
- `doc_path`: Documentation output path
203
- `nbs_path`: Notebooks source path
204
- `tst_flags`: Test execution flags
205
- `custom_sidebar`: Use custom sidebar
206
- `black_formatting`: Enable black code formatting
207
- `clean_ids`: Remove notebook cell IDs
208
- `jupyter_hooks`: Enable Jupyter git hooks
209

210
**Usage Example:**
211

212
```python
213
from nbdev.config import get_config
214

215
config = get_config()
216

217
# Access common settings
218
print(f"Package: {config.lib_name}")
219
print(f"Source: {config.lib_path}")  
220
print(f"Docs: {config.doc_path}")
221
print(f"Notebooks: {config.nbs_path}")
222
print(f"Version: {config.version}")
223
print(f"Git URL: {config.git_url}")
224
```