Copy edit changelog entry

dstansby · dstansby · commit c78c8103f82e · 2023-01-26T20:34:34.000Z
diff --git a/doc/users/next_whats_new/2018_12_03_sphinx_plot_preserve.rst b/doc/users/next_whats_new/2018_12_03_sphinx_plot_preserve.rst
diff --git a/doc/users/next_whats_new/sphinx_plot_preserve.rst b/doc/users/next_whats_new/sphinx_plot_preserve.rst
@@ -0,0 +1,32 @@
+Caching sphinx directive figure outputs
+---------------------------------------
+
+The new ``:outname:`` property for the Sphinx plot directive can
+be used to cache generated images. It is used like:
+
+.. code-block:: rst
+
+    .. plot::
+       :outname: stinkbug_plot
+
+       import matplotlib.pyplot as plt
+       import matplotlib.image as mpimg
+       import numpy as np
+       img = mpimg.imread('_static/stinkbug.png')
+       imgplot = plt.imshow(img)
+
+Without ``:outname:``, the figure generated above would normally be called,
+e.g. :file:`docfile3-4-01.png` or something equally mysterious. With
+``:outname:`` the figure generated will instead be named
+:file:`stinkbug_plot-01.png` or even :file:`stinkbug_plot.png`. This makes it
+easy to understand which output image is which and, more importantly, uniquely
+keys output images to the code snippets that generated them.
+
+Configuring the cache directory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The directory that images are cached to can be configured using the
+``plot_cache_dir`` configuration value in the Sphinx configuration file.
+
+If an image is already in ``plot_cache_dir`` when documentation is being
+generated, this image is copied to the build directory thereby pre-empting
+generation and reducing computation time in low-resource environments.
diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py
@@ -79,8 +79,8 @@
         is generated from a file.
     ``:outname:`` : str
         If specified, the names of the generated plots will start with the
-        value of `:outname:`. This is handy for preserving output results if
-        code is reordered between runs. The value of `:outname:` must be
+        value of ``:outname:``. This is handy for preserving output results if
+        code is reordered between runs. The value of ``:outname:`` must be
         unique across the generated documentation.
 
 Additionally, this directive supports all the options of the `image directive
