📖 Improve accessible figures with Jupyter docs (#1077)

* Improve accessible figures with Jupyter docs
* Clarify figure for a11y

docs/cross-references.md

@@ -207,7 +207,7 @@ See more about reusing Jupyter outputs in figures, adding placeholders, and othe
 
 The following example embeds a figure from [](./interactive-notebooks.ipynb), and can be used in cross references [](#fig-altair-horsepower).
 
-```{figure} #altair-horsepower
+```{figure} #img:altair-horsepower
 :label: fig-altair-horsepower
 This figure has been included from [](./interactive-notebooks.ipynb) and can be referred to in cross-references through a different label.
 ```

docs/embed.md

@@ -93,7 +93,7 @@ Here's a nice sunset with a caption!
 
 The new label can be referred to in this context, i.e. `[@sunset-figure]`: [@sunset-figure], which refers to the new figure rather than the original image. This allows you to scroll to embedded content on the page, rather than jumping to the original document. Note that this is especially useful with [embedding Jupyter Notebook outputs](./reuse-jupyter-outputs.md). For example:
 
-```{figure} #altair-horsepower
+```{figure} #img:altair-horsepower
 This figure has been included from a Jupyter Notebook and can be referred to in cross-references through a different label. See [](./reuse-jupyter-outputs.md) for more information.
 ```
 

docs/figures.md

@@ -1,6 +1,6 @@
 ---
 title: Images, Figures and Videos
-short_title: Images & Videos
+short_title: Images, Figures, & Videos
 description: MyST Markdown allows you to create images and figures in your documents, including cross-referencing content throughout your pages.
 thumbnail: ./thumbnails/figures.png
 ---

docs/reuse-jupyter-outputs.md

@@ -60,20 +60,49 @@ Any labeled Jupyter cell can be referred to using the standard [cross-reference]
 ```
 
 The cross-referenced cell will be shown in a hover-preview and link to the notebook cell directly.
-For example, [here we cross-reference a cell from the Jupyter Notebooks examples](#data-cars)
+For example, [here we cross-reference a cell from the Jupyter Notebooks examples](#tbl:data-cars)
 
 ## Embed a cell output
 
 Once a cell is labeled, you can embed its output with the standard [syntax for embedding content with MyST](embed.md).
 For example, the following code embeds a labeled cell defined in [](interactive-notebooks.ipynb):
 
 ```md
-![](#data-cars)
+![](#tbl:data-cars)
 ```
 
 It results in the following:
 
-![](#data-cars)
+![](#tbl:data-cars)
+
+:::{tip} Define one output per cell
+Embedding works best when you generate a single output per cell.
+This allows you to attach a label to one object instead of multiple, and generally makes life easier.
+If you'd like a single cell to generate multiple outputs for embedding, save each of them to a variable, and then use subsequent cells to display them as outputs.
+For example:
+
+```{code-block} python
+:filename: Cell 1
+# Generate two matplotlib figures
+fig1, ax1 = plt.subplots()
+fig2, ax2 = plt.subplots()
+```
+
+```{code-block} python
+:filename: Cell 2
+#| label: fig:plot1
+# Display the figure so that its output is labeled with `fig:plot1`
+fig1
+```
+
+```{code-block} python
+:filename: Cell 3
+#| label: fig:plot2
+# Display the figure so that its output is labeled with `fig:plot2`
+fig2
+```
+
+:::
 
 ## Embed the entire cell with the `{embed}` directive
 
@@ -84,14 +113,14 @@ For example, to embed **both the cell input and output**, use syntax like:
 
 ````
 % Embed both the input and output
-```{embed} #data-cars
+```{embed} #tbl:data-cars
 :remove-output: false
 :remove-input: false
 ```
 ````
 
 % Embed both the input and output
-```{embed} #data-cars
+```{embed} #tbl:data-cars
 :remove-output: false
 :remove-input: false
 ```
@@ -111,7 +140,7 @@ Below we give the figure a new `name` as well, so that we can cross-reference it
 
 The following example embeds a figure from [](./interactive-notebooks.ipynb).
 
-```{figure} #altair-horsepower
+```{figure} #img:altair-horsepower
 This figure has been included from [](./interactive-notebooks.ipynb) and can be referred to in cross-references through a different label.
 ```
 
@@ -141,6 +170,33 @@ print('hello world')
 
 In this case, the placeholder will replace _any_ output from the cell in static exports; outputs will only show up in interactive environments.
 
+### Alternative text for accessibility
+
+Adding alternative text to images allows you to provide context for the image for readers with assistive technologies, or unreliable internet connections.
+By default, Jupyter does not support alternative text for image outputs, but you can use MyST to add alternative text with the `{figure}` directive.
+See [](figures.md) for more details.
+
+
+Using the `{figure}` directive allows you to set one or more captions for your figures, which serve accessibility purposes as well.
+This works for both static outputs (like Matplotlib) as well as interactive ones (like Altair).
+For example, the following `{figure}` directive embeds two cell outputs with captions:
+
+````
+```{figure}
+
+![A matplotlib image of the cars data](#img:mpl)
+
+![An Altair visualization of the cars data!](#img:altair-horsepower)
+```
+````
+
+```{figure}
+
+![A matplotlib image of the cars data](#img:mpl)
+
+![An Altair visualization of the cars data!](#img:altair-horsepower)
+```
+
 ## Outputs as Tables
 
 You can wrap tabular outputs (e.g. Pandas DataFrames) with a `{table}` directive in order to assign a caption and include it with your figures.
@@ -155,15 +211,15 @@ For example:
 ````
 :::{table} This is my table
 :label: mytable
-![](#data-cars)
+![](#tbl:data-cars)
 :::
 ````
 
 Results in:
 
 :::{table} This is my table
 :label: mytable
-![](#data-cars)
+![](#tbl:data-cars)
 :::
 
 ### Use the `{figure}` directive with `kind: table`
@@ -172,7 +228,7 @@ This defines a figure but allows the content to be a table.
 For example, the following syntax:
 
 ````
-:::{figure} #data-cars
+:::{figure} #tbl:data-cars
 :label: myothertable
 :kind: table
 This is my table caption!
@@ -181,7 +237,7 @@ This is my table caption!
 
 Results in:
 
-:::{figure} #data-cars
+:::{figure} #tbl:data-cars
 :label: myothertable
 :kind: table
 This is my table caption!