📚 DOCS: Add "Inline variable evaluation" page

docs/computation/execute.md

@@ -15,10 +15,18 @@ See the sections below for a description of each configuration option and their
 
 (execute/config)=
 
-## Triggering notebook execution
+## Notebook execution modes
 
 To trigger the execution of notebook pages, use the global `nb_execution_mode` configuration key, or per-file `execution_mode` key:
 
+|   Mode   |                             Description                              |
+| -------- | -------------------------------------------------------------------- |
+| `off`    | Do not execute the notebook                                          |
+| `force`  | Always execute the notebook (before parsing)                         |
+| `auto`   | Execute notebooks with missing outputs (before parsing)              |
+| `cache`  | Execute notebook and store/retrieve outputs from a cache             |
+| `inline` | Execute the notebook during parsing (allows for variable evaluation) |
+
 By default this is set to:
 
 ```python
@@ -28,27 +36,39 @@ nb_execution_mode = "auto"
 This will only execute notebooks that are missing at least one output.
 If a notebook has *all* of its outputs populated, then it will not be executed.
 
-**To force the execution of all notebooks, regardless of their outputs**, change the above configuration value to:
+To force the execution of all notebooks, regardless of their outputs, change the above configuration value to:
 
 ```python
 nb_execution_mode = "force"
 ```
 
-**To cache execution outputs with [jupyter-cache]**, change the above configuration value to:
+To cache execution outputs with [jupyter-cache], change the above configuration value to:
 
 ```python
 nb_execution_mode = "cache"
 ```
 
 See {ref}`execute/cache` for more information.
 
-**To turn off notebook execution**, change the above configuration value to:
+To execute notebooks inline during parsing, change the above configuration value to:
+
+```python
+nb_execution_mode = "inline"
+```
+
+This allows for the use of `eval` roles/directives to embed variables, evaluated from the execution kernel, inline of the Markdown.
+
+See {ref}`render/eval` for more information.
+
+To turn off notebook execution, change the above configuration value to:
 
 ```python
 nb_execution_mode = "off"
 ```
 
-**To exclude certain file patterns from execution**, use the following configuration:
+## Exclude notebooks from execution
+
+To exclude certain file patterns from execution, use the following configuration:
 
 ```python
 nb_execution_excludepatterns = ['list', 'of', '*patterns']
@@ -124,7 +144,7 @@ By default, the command working directory (cwd) that a notebook runs in will be
 However, you can set `nb_execution_in_temp=True` in your `conf.py`, to change this behaviour such that, for each execution, a temporary directory will be created and used as the cwd.
 
 (execute/timeout)=
-## Execution Timeout
+## Execution timeout
 
 The execution of notebooks is managed by {doc}`nbclient <nbclient:client>`.
 
@@ -184,7 +204,7 @@ print(thisvariabledoesntexist)
 ```
 
 (execute/raise_on_error)=
-## Error Reporting: Warning vs. Failure
+## Error reporting: Warning vs. Failure
 
 When an error occurs in a context where `nb_execution_allow_errors=False`,
 the default behaviour is for this to be reported as a warning.

docs/render/glue.md

@@ -6,7 +6,7 @@ kernelspec:
 
 (glue/main)=
 
-# Embedding outputs as variables
+# Saving variables to embed (IPython only)
 
 You often wish to run analyses in a notebook and insert them into your
 documents text elsewhere.
@@ -19,8 +19,7 @@ then display those variables in a Markdown cell by referencing the key.
 This page describes how to add keys to variables in notebooks, and how to insert them
 into your book's content in a variety of ways.[^download]
 
-[^download]: This notebook can be downloaded as
-            **{nb-download}`glue.ipynb`** and {download}`glue.md`
+[^download]: This notebook can be downloaded as **{nb-download}`glue.ipynb`** and {download}`glue.md`
 
 :::{versionchanged} 0.14.0
 The `glue` roles and directives now only identify keys in the same notebook, by default.

docs/render/index.md

@@ -7,6 +7,7 @@ and build output formats.
 :maxdepth: 1
 format_code_cells
 hiding
-glue
 interactive
+inline
+glue
 ```

docs/render/inline.md

@@ -0,0 +1,50 @@
+---
+file_format: mystnb
+kernelspec:
+  name: python3
+mystnb:
+    execution_mode: 'inline'
+---
+
+(render/eval)=
+
+# Inline variable evaluation
+
+```{versionadded} 0.15.0
+```
+
+```{code-cell} ipython3
+a = 1
+```
+
+```{code-cell} ipython3
+import matplotlib.pyplot as plt
+myplot, ax = plt.subplots(figsize=(6, 2))
+ax.plot([1,2,3])
+ax.grid()
+plt.close()
+```
+
+`````markdown
+````{note}
+```{eval:figure} myplot
+My figure caption, with an inline variable: {eval}`a`.
+```
+````
+`````
+
+````{note}
+```{eval:figure} myplot
+My figure caption, with an inline variable: {eval}`a`.
+```
+````
+
+```{code-cell} ipython3
+a = 2
+```
+
+`````markdown
+Updated inline variable: {eval}`a`.
+`````
+
+Updated inline variable: {eval}`a`.