0
# Sphinx Extension
1
2
Core Sphinx integration functionality that enables MyST-NB to work as a Sphinx extension, providing notebook parsing, rendering, and post-processing capabilities within the Sphinx build system.
3
4
## Capabilities
5
6
### Extension Setup
7
8
Main Sphinx extension entry point that registers MyST-NB with a Sphinx application and configures all necessary components.
9
10
```python { .api }
11
def setup(app) -> dict:
12
"""
13
Sphinx extension setup function.
14
15
Parameters:
16
- app: Sphinx application instance
17
18
Returns:
19
dict: Extension metadata with version and parallel_read_safe flag
20
"""
21
```
22
23
### Sphinx Parser
24
25
Primary parser class that extends MyST-Parser to handle notebook content within Sphinx documents.
26
27
```python { .api }
28
class Parser(MystParser):
29
"""
30
Sphinx parser for MyST notebooks.
31
32
Extends MystParser to handle notebook-specific content and metadata.
33
Integrates with Sphinx's document processing pipeline.
34
"""
35
```
36
37
### Sphinx Renderer
38
39
Notebook content renderer specifically designed for Sphinx output formats, handling notebook cells, outputs, and metadata.
40
41
```python { .api }
42
class SphinxNbRenderer(SphinxRenderer, MditRenderMixin):
43
"""
44
Sphinx notebook renderer.
45
46
Combines SphinxRenderer capabilities with notebook-specific rendering
47
via MditRenderMixin. Handles conversion of notebook elements to
48
Sphinx doctree nodes.
49
"""
50
```
51
52
### Enhanced Build Environment
53
54
Extended Sphinx build environment that provides additional context and utilities for notebook processing.
55
56
```python { .api }
57
class SphinxEnvType(BuildEnvironment):
58
"""
59
Enhanced Sphinx build environment for notebook processing.
60
61
Extends standard BuildEnvironment with notebook-specific functionality
62
and context management.
63
"""
64
```
65
66
### Post-Processing Transforms
67
68
Sphinx post-transforms that modify the document tree after initial parsing to handle notebook-specific elements and behaviors.
69
70
```python { .api }
71
class SelectMimeType(SphinxPostTransform):
72
"""
73
Transform for selecting appropriate MIME types for output.
74
75
Processes notebook outputs and selects the best MIME representation
76
based on the target output format and configuration.
77
"""
78
79
class HideInputCells(SphinxPostTransform):
80
"""
81
Transform for hiding notebook input cells.
82
83
Conditionally hides code input cells based on configuration
84
and cell metadata tags.
85
"""
86
```
87
88
### Metadata Collection
89
90
Environment collector that gathers and manages notebook metadata throughout the Sphinx build process.
91
92
```python { .api }
93
class NbMetadataCollector(EnvironmentCollector):
94
"""
95
Collects and manages notebook metadata during Sphinx build.
96
97
Gathers execution metadata, cell tags, and other notebook-specific
98
information for use in rendering and cross-referencing.
99
"""
100
```
101
102
### Special Nodes
103
104
Custom Sphinx nodes for handling notebook-specific display elements and behaviors.
105
106
```python { .api }
107
class HideCodeCellNode(nodes.Element):
108
"""
109
Node representing a collapsible/hideable code cell.
110
111
Provides functionality for showing/hiding code cell content
112
based on user interaction or configuration.
113
"""
114
```
115
116
## Configuration Integration
117
118
The Sphinx extension integrates with Sphinx's configuration system, accepting configuration options prefixed with `nb_`:
119
120
- `nb_execution_mode`: Controls notebook execution behavior
121
- `nb_execution_timeout`: Sets execution timeout for cells
122
- `nb_render_plugin`: Specifies the rendering plugin to use
123
- `nb_remove_code_source`: Hide source code in output
124
- And 40+ additional configuration options
125
126
## Usage Examples
127
128
### Basic Extension Setup
129
130
```python
131
# In conf.py
132
extensions = ['myst_nb']
133
134
# Basic configuration
135
nb_execution_mode = "auto"
136
nb_execution_timeout = 30
137
nb_remove_code_source = False
138
```
139
140
### Advanced Configuration
141
142
```python
143
# In conf.py
144
extensions = ['myst_nb']
145
146
# Advanced notebook configuration
147
nb_execution_mode = "cache"
148
nb_execution_cache_path = ".jupyter_cache"
149
nb_execution_timeout = 120
150
nb_execution_in_temp = True
151
nb_merge_streams = True
152
nb_remove_code_outputs = False
153
nb_render_image_options = {"width": "100%"}
154
```
155
156
### Custom Renderer Plugin
157
158
```python
159
# In conf.py
160
extensions = ['myst_nb']
161
162
# Use custom renderer
163
nb_render_plugin = "my_custom_renderer"
164
165
# Register custom renderer entry point in setup.py:
166
# entry_points={
167
# "myst_nb.renderers": [
168
# "my_custom_renderer = mypackage.renderer:MyRenderer"
169
# ]
170
# }
171
```