0
# Configuration
1
2
Comprehensive configuration system for controlling notebook execution, display formatting, widget support, and build behavior. nbsphinx provides extensive configuration options through Sphinx's configuration system.
3
4
## Capabilities
5
6
### Execution Control
7
8
Configuration options for controlling when and how notebooks are executed during the Sphinx build process.
9
10
```python { .api }
11
# Configuration values added via app.add_config_value()
12
13
# Execution control
14
nbsphinx_execute = 'auto' # 'auto', 'always', 'never'
15
nbsphinx_kernel_name = '' # Jupyter kernel name for execution
16
nbsphinx_execute_arguments = [] # Arguments for kernel execution
17
nbsphinx_allow_errors = False # Allow errors during execution
18
nbsphinx_timeout = None # Execution timeout in seconds
19
```
20
21
Usage in `conf.py`:
22
23
```python
24
# Basic execution configuration
25
nbsphinx_execute = 'auto' # Execute only if no outputs present
26
nbsphinx_allow_errors = True # Continue build even if cells error
27
nbsphinx_timeout = 60 # 60 second timeout per cell
28
29
# Custom kernel
30
nbsphinx_kernel_name = 'python3'
31
nbsphinx_execute_arguments = ['--matplotlib=inline']
32
```
33
34
The `nbsphinx_execute` options:
35
- `'auto'` (default): Execute notebooks only if they have no stored outputs
36
- `'always'`: Always execute notebooks, ignoring stored outputs
37
- `'never'`: Never execute notebooks, use only stored outputs
38
39
### Display Formatting
40
41
Options for controlling the visual appearance of notebook content in the generated documentation.
42
43
```python { .api }
44
# Display formatting configuration
45
nbsphinx_codecell_lexer = 'none' # Syntax highlighter for code cells
46
nbsphinx_prompt_width = '4.5ex' # Width of input/output prompts
47
nbsphinx_responsive_width = '540px' # Responsive breakpoint width
48
nbsphinx_input_prompt = '[%s]:' # Template for input prompts
49
nbsphinx_output_prompt = '[%s]:' # Template for output prompts
50
```
51
52
Usage in `conf.py`:
53
54
```python
55
# Customize prompt appearance
56
nbsphinx_input_prompt = 'In [%s]:'
57
nbsphinx_output_prompt = 'Out[%s]:'
58
nbsphinx_prompt_width = '5ex'
59
60
# Set syntax highlighting
61
nbsphinx_codecell_lexer = 'python3'
62
63
# Responsive design
64
nbsphinx_responsive_width = '600px'
65
```
66
67
### Content Control
68
69
Configuration for adding content before and after notebook content and handling custom formats.
70
71
```python { .api }
72
# Content control configuration
73
nbsphinx_prolog = None # Content added before notebook content
74
nbsphinx_epilog = None # Content added after notebook content
75
nbsphinx_custom_formats = {} # Custom notebook format converters
76
```
77
78
Usage in `conf.py`:
79
80
```python
81
# Add common imports to all notebooks
82
nbsphinx_prolog = """
83
.. note::
84
This notebook was automatically generated from source code.
85
"""
86
87
# Add footer to all notebooks
88
nbsphinx_epilog = """
89
----
90
91
*Generated by nbsphinx*
92
"""
93
94
# Custom format support
95
nbsphinx_custom_formats = {
96
'.pct.py': 'jupytext.reads', # Support percent format
97
'.md': ['jupytext.reads', {'fmt': 'md'}], # Support markdown notebooks
98
}
99
```
100
101
### Widget Support
102
103
Configuration for Jupyter widget integration in HTML output.
104
105
```python { .api }
106
# Widget support configuration
107
nbsphinx_widgets_path = None # Path to widget bundle
108
nbsphinx_widgets_options = {} # Widget loading options
109
nbsphinx_requirejs_path = None # Path to require.js
110
nbsphinx_requirejs_options = None # Options for require.js loading
111
```
112
113
Usage in `conf.py`:
114
115
```python
116
# Enable widget support
117
nbsphinx_widgets_path = 'https://unpkg.com/@jupyter-widgets/html-manager@*/dist/embed-amd.js'
118
nbsphinx_widgets_options = {
119
'async': True,
120
}
121
122
# Custom require.js configuration
123
nbsphinx_requirejs_path = 'https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js'
124
nbsphinx_requirejs_options = {
125
'integrity': 'sha256-1fEPhSsRKlFKGfK3eO710tEweHh1fwokU5wFGDHO+vg=',
126
'crossorigin': 'anonymous',
127
}
128
```
129
130
Default widget settings are configured automatically when widgets are detected in notebooks.
131
132
### Gallery Features
133
134
Configuration for thumbnail galleries and custom thumbnail handling.
135
136
```python { .api }
137
# Gallery configuration
138
nbsphinx_thumbnails = {} # Custom thumbnail configurations
139
```
140
141
Usage in `conf.py`:
142
143
```python
144
# Custom thumbnails for specific notebooks
145
nbsphinx_thumbnails = {
146
'examples/basic-plotting': 'images/basic-plot-thumb.png',
147
'examples/advanced-*': 'images/advanced-thumb.png', # Glob patterns
148
'tutorials/**': 'images/tutorial-thumb.png',
149
}
150
```
151
152
Thumbnails can also be specified in notebook metadata:
153
154
```json
155
{
156
"nbsphinx-thumbnail": {
157
"output-index": 0,
158
"tooltip": "Custom tooltip for gallery"
159
}
160
}
161
```
162
163
### Math Support
164
165
Configuration for mathematical equation rendering.
166
167
```python { .api }
168
# Math support configuration
169
nbsphinx_assume_equations = True # Enable equation support by default
170
```
171
172
Usage in `conf.py`:
173
174
```python
175
# Disable automatic equation support
176
nbsphinx_assume_equations = False
177
```
178
179
When enabled, nbsphinx automatically configures MathJax for proper rendering of LaTeX math in notebooks.
180
181
### Configuration Examples
182
183
Complete configuration examples for common use cases:
184
185
```python
186
# conf.py - Basic configuration
187
extensions = ['nbsphinx']
188
189
# Execute all notebooks
190
nbsphinx_execute = 'always'
191
nbsphinx_allow_errors = True
192
nbsphinx_timeout = 120
193
194
# Custom styling
195
nbsphinx_input_prompt = 'In [%s]:'
196
nbsphinx_output_prompt = 'Out[%s]:'
197
nbsphinx_prompt_width = '5ex'
198
```
199
200
```python
201
# conf.py - Advanced configuration
202
extensions = ['nbsphinx', 'sphinx.ext.mathjax']
203
204
# Execution with custom kernel
205
nbsphinx_execute = 'auto'
206
nbsphinx_kernel_name = 'myproject'
207
nbsphinx_execute_arguments = ['--matplotlib=widget']
208
nbsphinx_timeout = 300
209
210
# Widget support
211
nbsphinx_widgets_path = 'https://unpkg.com/@jupyter-widgets/html-manager@*/dist/embed-amd.js'
212
213
# Custom content
214
nbsphinx_prolog = """
215
.. raw:: html
216
217
<style>
218
.nbinput .prompt, .nboutput .prompt {
219
background: #f0f0f0;
220
}
221
</style>
222
"""
223
224
# Gallery thumbnails
225
nbsphinx_thumbnails = {
226
'examples/*': '_static/example-thumb.png',
227
}
228
```
229
230
All configuration values support Sphinx's standard rebuild behavior (env, html, or none) to optimize build performance when configuration changes.