1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
|
---
file_format: mystnb
kernelspec:
name: python3
mystnb:
execution_mode: 'inline'
---
(render/eval)=
# Inline variable evaluation (eval)
```{versionadded} 0.15.0
```
The `eval` submodule allows you to insert code variables directly into the text flow of your documentation.
Use of `eval` requires that the [notebook execution mode](execute/modes) is set to `inline`, since the variables are evaluated by the notebook kernel.
For example, using the [top-matter](authoring/text-notebooks):
```yaml
---
file_format: mystnb
kernelspec:
name: python3
mystnb:
execution_mode: 'inline'
---
```
## Basic example
Below we set a variable `v1` within a code cell.
```{code-cell} ipython3
v1 = "My variable"
```
Using the `eval` role, we can insert the variable `v1` into the text of a paragraph:
`` {eval}`v1` `` -> {eval}`v1`
If we update the variable, we can see the change reflected in subsequent evaluation:
```{code-cell} ipython3
v1 = "My new variable"
```
`` {eval}`v1` `` -> {eval}`v1`
:::{important}
Variable names must match the regex `[a-zA-Z][a-zA-Z0-9_]*`
:::
## Inserting different output types
Any variable type can be inserted into the text flow using the `eval` role,
and the most suitable output type will be used, based on the output format (see {ref}`render/output/priority` for more information).
For example:
```{code-cell} ipython3
import ipywidgets as widgets
slider = widgets.IntSlider(value=5, min=0, max=10)
```
An inline slider (`` {eval}`slider` ``): {eval}`slider`
You can also use the `eval` directive to insert variables as blocks:
```{code-cell} ipython3
import matplotlib.pyplot as plt
myplot, ax = plt.subplots(figsize=(6, 2))
mean = 2.0
ax.plot([1,2,3])
ax.grid()
plt.close()
```
using:
````markdown
```{eval} myplot
```
````
gives:
```{eval} myplot
```
## Embedding outputs in figures
The `eval:figure` directive allows you to embed outputs in a figure,
with an optional caption and other formatting options.
For example, we can embed the output of the above plot in a figure:
`````markdown
```{eval:figure} myplot
:name: myplot
My plot with a mean value of {eval}`mean`.
```
`````
which gives:
```{eval:figure} myplot
:name: myplot
My plot with a mean value of {eval}`mean`.
```
That can be referenced with `` {ref}`myplot` ``: {ref}`myplot`
The following directive options are available:
:::{table} `eval:figure` directive options
| Option | Type | Description |
| ------ | ---- | ----------- |
| figwidth | length or percentage | The width of the figure |
| figclass | text | A space-separated list of class names for the figure |
| name | text | referenceable label for the figure |
| alt | text | Alternate text of an image |
| height | length | The desired height of an image |
| width | length or percentage | The width of an image |
| scale | percentage | The uniform scaling factor of an image |
| class | text | A space-separated list of class names for the image |
| align | text | left, center, or right |
:::
|
