0
# Sphinx Extension Setup
1

2
Core functionality for registering nbsphinx as a Sphinx extension, including configuration values, directives, parsers, and event handlers that integrate with the Sphinx build system.
3

4
## Capabilities
5

6
### Extension Initialization
7

8
The primary entry point that registers nbsphinx with Sphinx, configuring all parsers, directives, transforms, and event handlers.
9

10
```python { .api }
11
def setup(app):
12
    """
13
    Initialize Sphinx extension.
14
    
15
    Parameters:
16
    - app: Sphinx application object
17
    
18
    Returns:
19
    dict: Extension metadata containing:
20
        - version: str, nbsphinx version
21
        - parallel_read_safe: bool, True (supports parallel reading)
22
        - parallel_write_safe: bool, True (supports parallel writing)  
23
        - env_version: int, environment version number
24
    """
25
```
26

27
Usage example:
28

29
```python
30
# In conf.py
31
extensions = ['nbsphinx']
32

33
# The setup() function is called automatically by Sphinx
34
# when the extension is loaded
35
```
36

37
### Event Handlers
38

39
Functions that handle Sphinx build lifecycle events for notebook processing and asset management.
40

41
```python { .api }
42
def config_inited(app, config):
43
    """Handle Sphinx config-inited event for extension configuration."""
44

45
def builder_inited(app):
46
    """Handle Sphinx builder-inited event for build setup."""
47

48
def html_page_context(app, pagename, templatename, context, doctree):
49
    """Handle Sphinx html-page-context event to add CSS files."""
50

51
def html_collect_pages(app):
52
    """Handle Sphinx html-collect-pages event to copy local files."""
53

54
def env_updated(app, env):
55
    """Handle Sphinx env-updated event for widget configuration."""
56

57
def doctree_resolved(app, doctree, fromdocname):
58
    """Handle Sphinx doctree-resolved event for gallery processing."""
59

60
def env_merge_info(app, env, docnames, other):
61
    """Handle Sphinx env-merge-info event for parallel builds."""
62

63
def env_purge_doc(app, env, docname):
64
    """Handle Sphinx env-purge-doc event to remove document data."""
65
```
66

67
### Asset Management
68

69
Functions for managing static assets, copying files, and handling JavaScript dependencies.
70

71
```python { .api }  
72
def load_requirejs(app):
73
    """Load require.js for widget support."""
74

75
def backwards_compat_overwrite(copyfile=sphinx.util.copyfile):
76
    """Return kwargs dictionary to pass to copyfile() for consistent behavior."""
77

78
def patched_toctree_resolve(self, docname, builder, toctree, *args, **kwargs):
79
    """
80
    Monkey-patch for Sphinx's TocTree adapter.
81
    
82
    Parameters:
83
    - self: TocTree adapter instance
84
    - docname: str, document name
85
    - builder: Sphinx builder instance
86
    - toctree: toctree node
87
    - *args, **kwargs: additional arguments
88
    
89
    Returns:
90
    Resolved toctree structure
91
    """
92
```
93

94
Usage example:
95

96
```python
97
# Assets are managed automatically during build
98
# JavaScript and CSS files are included based on notebook content
99
```
100

101
### Extension Registration
102

103
The setup function registers various components with Sphinx:
104

105
- Source parser for `.ipynb` files
106
- Custom directives (nbinput, nboutput, nbgallery, etc.)
107
- Document node types (CodeAreaNode, FancyOutputNode, etc.) 
108
- Document transforms (RewriteLocalLinks, CreateSectionLabels, etc.)
109
- Configuration values (20+ options for controlling behavior)
110
- Event handlers for build lifecycle integration
111

112
```python
113
def setup(app):
114
    # Register source parser
115
    app.add_source_parser(NotebookParser)
116
    
117
    # Add configuration values (20+ options)
118
    app.add_config_value('nbsphinx_execute', 'auto', rebuild='env')
119
    app.add_config_value('nbsphinx_allow_errors', False, rebuild='')
120
    app.add_config_value('nbsphinx_timeout', None, rebuild='')
121
    app.add_config_value('nbsphinx_codecell_lexer', 'none', rebuild='env')
122
    app.add_config_value('nbsphinx_prompt_width', '4.5ex', rebuild='html')
123
    # ... 15+ more config values
124
    
125
    # Add directives
126
    app.add_directive('nbinput', NbInput)
127
    app.add_directive('nboutput', NbOutput)
128
    app.add_directive('nbinfo', NbInfo)
129
    app.add_directive('nbwarning', NbWarning)
130
    app.add_directive('nbgallery', NbGallery)
131
    app.add_directive('nblinkgallery', NbLinkGallery)
132
    
133
    # Add document nodes with visitor functions
134
    app.add_node(CodeAreaNode, 
135
                 html=(do_nothing, depart_codearea_html),
136
                 latex=(visit_codearea_latex, depart_codearea_latex),
137
                 text=(do_nothing, do_nothing))
138
    app.add_node(FancyOutputNode,
139
                 html=(do_nothing, do_nothing),
140
                 latex=(visit_fancyoutput_latex, depart_fancyoutput_latex),
141
                 text=(do_nothing, do_nothing))
142
    # ... more nodes
143
    
144
    # Connect event handlers  
145
    app.connect('builder-inited', builder_inited)
146
    app.connect('config-inited', config_inited)
147
    app.connect('html-page-context', html_page_context)
148
    app.connect('html-collect-pages', html_collect_pages)
149
    app.connect('env-updated', env_updated)
150
    app.connect('doctree-resolved', doctree_resolved)
151
    app.connect('env-merge-info', env_merge_info)
152
    app.connect('env-purge-doc', env_purge_doc)
153
    
154
    # Add transforms
155
    app.add_transform(CreateSectionLabels)
156
    app.add_transform(CreateDomainObjectLabels) 
157
    app.add_transform(RewriteLocalLinks)
158
    app.add_post_transform(GetSizeFromImages)
159
    
160
    # Add LaTeX package
161
    app.add_latex_package('nbsphinx')
162
    
163
    # Register code directive and monkey-patch TocTree
164
    rst.directives.register_directive('code', sphinx.directives.code.CodeBlock)
165
    
166
    return {
167
        'version': __version__,
168
        'parallel_read_safe': True,
169
        'parallel_write_safe': True,
170
        'env_version': 4,
171
    }
172

173
### Node Visitor Functions
174

175
Functions that handle rendering of custom nodes in different output formats during document processing.
176

177
```python { .api }
178
def depart_codearea_html(self, node):
179
    """HTML visitor for departing code area nodes."""
180

181
def visit_codearea_latex(self, node):
182
    """LaTeX visitor for visiting code area nodes."""
183

184
def depart_codearea_latex(self, node):
185
    """LaTeX visitor for departing code area nodes."""
186

187
def visit_fancyoutput_latex(self, node):
188
    """LaTeX visitor for visiting fancy output nodes."""
189

190
def depart_fancyoutput_latex(self, node):
191
    """LaTeX visitor for departing fancy output nodes."""
192

193
def visit_admonition_html(self, node):
194
    """HTML visitor for visiting admonition nodes."""
195

196
def depart_admonition_html(self, node):
197
    """HTML visitor for departing admonition nodes."""
198

199
def visit_admonition_latex(self, node):
200
    """LaTeX visitor for visiting admonition nodes."""
201

202
def depart_admonition_latex(self, node):
203
    """LaTeX visitor for departing admonition nodes."""
204

205
def visit_admonition_text(self, node):
206
    """Text visitor for visiting admonition nodes."""
207

208
def depart_admonition_text(self, node):
209
    """Text visitor for departing admonition nodes."""
210

211
def depart_gallery_html(self, node):
212
    """HTML visitor for departing gallery nodes."""
213

214
def do_nothing(self, node):
215
    """No-op visitor function for nodes that don't need processing."""
216
```