0
# Custom Directives
1

2
Specialized reStructuredText directives for displaying notebook content including input cells, output cells, galleries, and admonitions. These directives provide the building blocks for rendering notebook content in Sphinx documentation.
3

4
## Capabilities
5

6
### Input Cell Directive
7

8
Displays notebook input cells with syntax highlighting, execution counts, and formatting options.
9

10
```python { .api }
11
class NbInput(rst.Directive):
12
    """
13
    A notebook input cell with prompt and code area.
14
    
15
    Options:
16
    - execution-count: int, execution count number for prompt
17
    - empty-lines-before: int, number of empty lines before code
18
    - empty-lines-after: int, number of empty lines after code  
19
    - no-output: flag, indicates cell has no output
20
    """
21
    
22
    required_arguments = 0
23
    optional_arguments = 1  # lexer name
24
    final_argument_whitespace = False
25
    option_spec = {
26
        'execution-count': rst.directives.positive_int,
27
        'empty-lines-before': rst.directives.nonnegative_int,
28
        'empty-lines-after': rst.directives.nonnegative_int,
29
        'no-output': rst.directives.flag,
30
    }
31
    has_content = True
32
    
33
    def run(self):
34
        """This is called by the reST parser."""
35
```
36

37
Usage example:
38

39
```rst
40
.. nbinput:: python
41
   :execution-count: 1
42
   :empty-lines-before: 1
43

44
   import numpy as np
45
   import matplotlib.pyplot as plt
46
   
47
   x = np.linspace(0, 10, 100)
48
   y = np.sin(x)
49
   plt.plot(x, y)
50
```
51

52
### Output Cell Directive
53

54
Displays notebook output cells with optional prompts, execution counts, and formatting.
55

56
```python { .api }
57
class NbOutput(rst.Directive):
58
    """
59
    A notebook output cell with optional prompt.
60
    
61
    Options:
62
    - execution-count: int, execution count number for prompt
63
    - more-to-come: flag, indicates more outputs follow
64
    - fancy: flag, enables fancy output formatting
65
    - class: str, CSS class for styling
66
    """
67
    
68
    required_arguments = 0
69
    final_argument_whitespace = False
70
    option_spec = {
71
        'execution-count': rst.directives.positive_int,
72
        'more-to-come': rst.directives.flag,
73
        'fancy': rst.directives.flag,
74
        'class': rst.directives.unchanged,
75
    }
76
    has_content = True
77
    
78
    def run(self):
79
        """This is called by the reST parser."""
80
```
81

82
Usage example:
83

84
```rst
85
.. nboutput::
86
   :execution-count: 1
87
   :fancy:
88

89
   .. image:: output_1_0.png
90
      :class: no-scaled-link
91
```
92

93
### Gallery Directives
94

95
Creates thumbnail galleries for notebook collections with optional captions and custom thumbnails.
96

97
```python { .api }
98
class NbGallery(sphinx.directives.other.TocTree):
99
    """
100
    A thumbnail gallery for notebooks.
101
    
102
    Inherits all toctree options and functionality.
103
    Displays linked notebooks as a grid of thumbnails.
104
    """
105
    
106
    def run(self):
107
        """Wrap GalleryToc around toctree."""
108

109
class NbLinkGallery(NbGallery):
110
    """
111
    A thumbnail gallery for notebooks as links.
112
    
113
    Similar to NbGallery but creates link-only galleries
114
    that don't affect document hierarchy. Only supports
115
    a subset of toctree options.
116
    """
117
    
118
    option_spec = {
119
        'name': rst.directives.unchanged,
120
        'caption': rst.directives.unchanged_required,
121
        'glob': rst.directives.flag,
122
        'reversed': rst.directives.flag,
123
    }
124
```
125

126
Usage examples:
127

128
```rst
129
.. nbgallery::
130
   :caption: Example Notebooks
131
   :name: example-gallery
132

133
   notebook1
134
   notebook2
135
   notebook3
136

137
.. nblinkgallery::  
138
   :caption: Related Examples
139
   :glob:
140

141
   examples/*
142
```
143

144
### Admonition Directives
145

146
Information and warning boxes for highlighting important content in notebooks.
147

148
```python { .api }
149
class _NbAdmonition(rst.Directive):
150
    """Base class for NbInfo and NbWarning."""
151
    
152
    required_arguments = 0
153
    optional_arguments = 0
154
    option_spec = {}
155
    has_content = True
156
    
157
    def run(self):
158
        """This is called by the reST parser."""
159

160
class NbInfo(_NbAdmonition):
161
    """
162
    An information box.
163
    
164
    Creates a styled information admonition.
165
    """
166
    _class = 'note'
167

168
class NbWarning(_NbAdmonition):
169
    """
170
    A warning box.
171
    
172
    Creates a styled warning admonition.
173
    """
174
    _class = 'warning'
175
```
176

177
Usage examples:
178

179
```rst
180
.. nbinfo::
181

182
   This notebook demonstrates advanced plotting techniques.
183
   Make sure you have matplotlib installed.
184

185
.. nbwarning::
186

187
   The following code requires GPU acceleration and may
188
   take several minutes to execute.
189
```
190

191
### Document Nodes
192

193
Custom docutils nodes that represent notebook elements in the document tree.
194

195
```python { .api }
196
class CodeAreaNode(docutils.nodes.Element):
197
    """Input area or plain-text output area of a Jupyter notebook code cell."""
198

199
class FancyOutputNode(docutils.nodes.Element):
200
    """A custom node for non-plain-text output of code cells."""
201

202
class AdmonitionNode(docutils.nodes.Element):
203
    """A custom node for info and warning boxes."""
204

205
class GalleryToc(docutils.nodes.Element):
206
    """A wrapper node used for creating galleries."""
207

208
class GalleryNode(docutils.nodes.Element):
209
    """A custom node for thumbnail galleries."""
210

211
class DummyTocTree(docutils.nodes.Element):
212
    """A dummy node to replace and disable sphinx.addnodes.toctree."""
213
```
214

215
These nodes are created automatically by the directives and processed by visitor functions during HTML/LaTeX output generation.
216

217
## Node Creation
218

219
Helper function for creating code cell nodes with proper styling and attributes.
220

221
```python { .api }
222
def _create_code_nodes(directive):
223
    """
224
    Create nodes for an input or output code cell.
225
    
226
    Parameters:
227
    - directive: rst.Directive, the directive being processed
228
    
229
    Returns:
230
    list: List of docutils nodes representing the cell
231
    """
232
```
233

234
## Visitor Functions
235

236
Functions that handle rendering of custom nodes in different output formats (HTML, LaTeX, text). These are registered with Sphinx and called automatically during document processing:
237

238
- `visit_codearea_latex`, `depart_codearea_latex`
239
- `visit_fancyoutput_latex`, `depart_fancyoutput_latex`  
240
- `visit_admonition_html`, `depart_admonition_html`
241
- `visit_admonition_latex`, `depart_admonition_latex`
242
- `depart_gallery_html`
243

244
The visitor functions ensure that notebook content renders correctly across different Sphinx output formats while preserving styling and functionality.