0
# Glue System
1
2
Variable gluing system for cross-referencing computed results across notebook cells and documentation. The glue system enables storing and referencing variables, plots, and other outputs to create dynamic, interconnected documentation.
3
4
## Capabilities
5
6
### Core Glue Function
7
8
Main function for gluing variables into notebook cell metadata for later reference.
9
10
```python { .api }
11
def glue(name: str, variable, display: bool = True) -> None:
12
"""
13
Glue a variable into the notebook's cell metadata.
14
15
Parameters:
16
- name: str - Unique name for the variable for later reference
17
- variable: Any - Python object whose display value should be stored
18
- display: bool - Whether to display the object when gluing (default True)
19
20
The stored information is what is displayed when you print or show
21
the object in a Jupyter Notebook, not the object itself.
22
"""
23
```
24
25
### Sphinx Integration
26
27
Integration functions for loading glue functionality into Sphinx applications.
28
29
```python { .api }
30
def load_glue_sphinx(app: Sphinx) -> None:
31
"""
32
Load glue functionality for Sphinx applications.
33
34
Parameters:
35
- app: Sphinx application instance
36
37
Registers glue roles, directives, and domain with Sphinx.
38
"""
39
```
40
41
### Docutils Integration
42
43
Integration functions for loading glue functionality into standalone docutils applications.
44
45
```python { .api }
46
def load_glue_docutils(app: DocutilsApp) -> None:
47
"""
48
Load glue functionality for docutils applications.
49
50
Parameters:
51
- app: DocutilsApp container for roles and directives
52
53
Registers glue roles and directives with docutils.
54
"""
55
```
56
57
## Roles and Directives
58
59
### Glue Role
60
61
Inline role for inserting glued content into text.
62
63
```python { .api }
64
class GlueRole:
65
"""
66
Inline role to insert glued variable content.
67
68
Usage: :glue:`variable_name`
69
"""
70
```
71
72
### Glue Directive
73
74
Block directive for inserting glued content as a block element.
75
76
```python { .api }
77
class GlueDirective:
78
"""
79
Block directive to insert glued variable content.
80
81
Usage:
82
```{glue} variable_name
83
```
84
"""
85
```
86
87
### Glue Figure Directive
88
89
Specialized directive for inserting glued content as a figure with caption and referencing support.
90
91
```python { .api }
92
class GlueFigureDirective:
93
"""
94
Figure directive for glued content with caption support.
95
96
Usage:
97
```{glue:figure} variable_name
98
:name: "figure-name"
99
:align: center
100
101
Figure caption text
102
```
103
"""
104
```
105
106
## Sphinx Domain
107
108
### Glue Domain
109
110
Sphinx domain that manages glue functionality and cross-references.
111
112
```python { .api }
113
class GlueDomain:
114
"""
115
Sphinx domain for glue functionality.
116
117
Manages glue variable storage, cross-referencing, and
118
integration with Sphinx's reference system.
119
"""
120
```
121
122
## Usage Examples
123
124
### Basic Variable Gluing
125
126
```python
127
from myst_nb import glue
128
import numpy as np
129
import matplotlib.pyplot as plt
130
131
# Glue a simple value
132
result = 42 * 1.5
133
glue("calculation_result", result)
134
135
# Glue an array
136
data = np.array([1, 2, 3, 4, 5])
137
glue("my_array", data)
138
139
# Glue a plot
140
fig, ax = plt.subplots()
141
ax.plot([1, 2, 3, 4], [1, 4, 2, 3])
142
ax.set_title("Sample Plot")
143
glue("sample_plot", fig, display=False)
144
```
145
146
### Inline References
147
148
In MyST markdown:
149
150
```markdown
151
The calculation result is {glue:}`calculation_result`.
152
153
Our array contains {glue:}`my_array`.
154
```
155
156
### Block References
157
158
```markdown
159
Here is our data:
160
161
```{glue} my_array
162
```
163
```
164
165
### Figure References
166
167
```markdown
168
```{glue:figure} sample_plot
169
:name: "fig-sample"
170
:align: center
171
172
This is our sample plot showing the trend.
173
```
174
175
Later reference: {numref}`fig-sample` shows the results.
176
```
177
178
### Advanced Gluing with DataFrames
179
180
```python
181
import pandas as pd
182
from myst_nb import glue
183
184
# Create and glue a DataFrame
185
df = pd.DataFrame({
186
'A': [1, 2, 3],
187
'B': [4, 5, 6],
188
'C': [7, 8, 9]
189
})
190
glue("results_table", df)
191
192
# Glue summary statistics
193
glue("mean_A", df['A'].mean())
194
glue("max_B", df['B'].max())
195
```
196
197
Reference in markdown:
198
```markdown
199
## Results
200
201
```{glue:figure} results_table
202
:name: "table-results"
203
204
Summary of results
205
```
206
207
The mean of column A is {glue:}`mean_A` and maximum of B is {glue:}`max_B`.
208
```
209
210
### Conditional Display
211
212
```python
213
from myst_nb import glue
214
215
# Glue without immediate display for later use only
216
sensitive_data = compute_sensitive_results()
217
glue("internal_calc", sensitive_data, display=False)
218
219
# Display-friendly version
220
public_summary = create_summary(sensitive_data)
221
glue("public_results", public_summary, display=True)
222
```
223
224
### Cross-Notebook References
225
226
Variables glued in one notebook can be referenced in other notebooks within the same Sphinx project:
227
228
Notebook 1:
229
```python
230
glue("shared_constant", 3.14159)
231
```
232
233
Notebook 2:
234
```markdown
235
Using the constant {glue:}`shared_constant` from the previous analysis...
236
```
237
238
## Configuration Options
239
240
The glue system respects various configuration options:
241
242
- Output format handling for different MIME types
243
- Figure size and alignment options
244
- Cross-reference numbering and styling
245
- Display precision for numeric values
246
247
Integration with MyST-NB's broader configuration system ensures consistent behavior across all glued content.