Plot directive preserve #10149

r-barnes · 2018-01-03T20:15:37Z

PR Summary

The Sphinx plot directive can be used to automagically generate figures for documentation like so:

.. 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)

But, if you reorder the figures in the documentation then all the figures may need to be rebuilt. This takes time. The names given to the figures are also fairly meaningless, making them more difficult to index by search engines or to find on a filesystem.

Alternatively, if you are compiling on a limited-resource service like ReadTheDocs, you may wish to build imagery locally to avoid hitting resource limits on the server. Using the new changes allows extensive dynamically generated imagery to be used on services like ReadTheDocs.

The `:outname:` property

These problems are addressed through two new features in the plot directive. The first is the introduction of the :outname: property. It is used like so:

.. 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. docfile3-4-01.png or something equally mysterious. With :outname: the figure generated will instead be named stinkbug_plot-01.png or even stinkbug_plot.png. This makes it easy to understand which output image is which and, more importantly, uniquely keys output images to code snippets.

The `plot_preserve_dir` configuration value

Setting the plot_preserve_dir configuration value to the name of a directory will cause all images with :outname: set to be copied to this directory upon generation.

If an image is already in plot_preserve_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.

Related issues were raised on ReadTheDocs (link) and on StackOverflow (link).

PR Checklist

Has Pytest style unit tests
It would, but I'm not sure how to go about writing them. Sorry :-/
Code is PEP 8 compliant
Leastwise, nothing new is added to the numerous pre-existing violations. PEP8 adherence makes code difficult to read :-/
New features are documented, with examples if plot related
Documentation is sphinx and numpydoc compliant
Added an entry to doc/users/next_whats_new/ if major new feature (follow instructions in README.rst there)
Documented in doc/api/api_changes.rst if API changed in a backward-incompatible way

tacaswell · 2018-01-03T20:49:48Z

👍 in principle, but the docs need to build cleanly!

jklymak · 2018-01-03T21:27:40Z

lib/matplotlib/sphinxext/plot_directive.py

@@ -656,6 +674,9 @@ def render_figures(code, code_path, output_dir, output_base, context,
            for format, dpi in formats:
                try:
                    figman.canvas.figure.savefig(img.filename(format), dpi=dpi)
+                    if config.plot_preserve_dir and outname:
+                      print("Preserving '{0}' into '{1}'".format(img.filename(format), config.plot_preserve_dir))


Not reviewing, but I don't think you want print in here do you? I'd do _log.info or _log.debug?

Yes, that's probably what I want, but I didn't know about them. I'll update.

Actually, I don't see _log as a variable in the plot_directive.py namespace, so I'm not sure how to make that adjustment.

If its not already in this module, then up at the top:

# ... other imports import logging # ... other imports _log = logging.getLogger(__name__)

Thanks: got that up.

lib/matplotlib/sphinxext/plot_directive.py

r-barnes · 2018-01-22T20:57:31Z

Eliminated some spaces

jklymak · 2019-07-24T13:53:05Z

@r-barnes sorry this didn't get a second review yet. If you give it a rebase and ping me I'll give it a quick look and merge on the basis of @tacaswell 's approval. We are about to branch 3.2, so it'd be nice to get this in

timhoffm · 2019-07-24T19:58:41Z

Wouldn't plot_preserve_dir better be named plot_cache_dir?

tacaswell

Mostly the indentation needs to be fixed.

@r-barnes I am going to do the rebase and force-push to your branch

lib/matplotlib/sphinxext/plot_directive.py

tacaswell · 2019-08-11T23:05:44Z

lib/matplotlib/sphinxext/plot_directive.py

+    if config.plot_preserve_dir and outname:
+      outfiles = glob.glob(os.path.join(config.plot_preserve_dir, outname) + '*')
+      for of in outfiles:
+        _log.info("Copying preserved copy of '{0}' into '{1}'".format(of, build_dir))


we are py36+ so we can use f-strings 😄

tacaswell · 2019-08-12T00:35:52Z

sorry, I read the year when this was opened wrong and thought it was from this January, not from 2 years ago.

I did the re-base and added the leading spaces

lib/matplotlib/sphinxext/plot_directive.py

anntzer

modulo tests passing

timhoffm · 2019-11-24T18:16:42Z

I took the liberty of pushing an update to fix the doc issues.

timhoffm

Needs a rebase on master. Then move whats new entry to our new whats new scheme.

timhoffm · 2019-11-24T18:18:06Z

lib/matplotlib/sphinxext/plot_directive.py

@@ -519,7 +548,7 @@ def get_plot_formats(config):

 def render_figures(code, code_path, output_dir, output_base, context,
                   function_name, config, context_reset=False,
-                   close_figs=False):
+                   close_figs=False, outname=''):


Would go with outname=None, which is IMHO a more standard way for "not defined" than an empty string.

timhoffm · 2019-11-24T18:19:27Z

doc/users/next_whats_new/2018_12_03_sphinx_plot_preserve.rst

@@ -0,0 +1,61 @@
+Plot Directive `outname` and `plot_preserve_dir`


I propose to rename plot_preserve_dir to plot_cache_dir.

dstansby · 2023-01-30T09:47:18Z

See #25091 (comment) for context on closing.

tacaswell added this to the v2.2 milestone Jan 3, 2018

jklymak reviewed Jan 3, 2018

View reviewed changes

tacaswell approved these changes Jan 4, 2018

View reviewed changes

has2k1 reviewed Jan 5, 2018

View reviewed changes

lib/matplotlib/sphinxext/plot_directive.py Outdated Show resolved Hide resolved

jklymak modified the milestones: needs sorting, v3.0 Mar 16, 2018

jklymak added Documentation status: needs rebase labels Mar 16, 2018

anntzer added topic: sphinx extension and removed Documentation labels May 24, 2018

jklymak modified the milestones: v3.0, v3.1 Jul 9, 2018

tacaswell modified the milestones: v3.1, v3.2 Feb 1, 2019

jklymak added the Release critical For bugs that make the library unusable (segfaults, incorrect plots, etc) and major regressions. label Jul 24, 2019

tacaswell previously requested changes Aug 11, 2019

View reviewed changes

tacaswell force-pushed the plot_directive_preserve branch from e222429 to e238368 Compare August 12, 2019 00:34

tacaswell removed the status: needs rebase label Aug 12, 2019

tacaswell requested a review from alexrudy August 12, 2019 00:43

ivanov reviewed Aug 19, 2019

View reviewed changes

lib/matplotlib/sphinxext/plot_directive.py Outdated Show resolved Hide resolved

anntzer approved these changes Aug 19, 2019

View reviewed changes

r-barnes added 3 commits August 19, 2019 15:39

Added :outname: option and plot_preserve_dir configuration value

b8c5559

Added What's New for plot directive changes

d4c41ff

Futzing with PEP8 whitespace stuff.

69356da

r-barnes and others added 6 commits August 19, 2019 15:39

Examples of using rst need to be code blocks

0ee71f0

Use logging instead of print

082298e

Satisfy PEP8 checks

73858c1

FIX: issue with rebase due to re-naming of local variables

74e9fbc

STY: fix line length and indentation issues

cd78416

STY: trim whitespace and add trailing comma

725f25d

tacaswell force-pushed the plot_directive_preserve branch from e9fe4f7 to 725f25d Compare August 19, 2019 19:39

tacaswell removed the Release critical For bugs that make the library unusable (segfaults, incorrect plots, etc) and major regressions. label Sep 4, 2019

tacaswell modified the milestones: v3.2.0, v3.3.0 Sep 4, 2019

jklymak added the status: needs revision label Oct 1, 2019

Fix doc style

134aaf9

timhoffm force-pushed the plot_directive_preserve branch from 2c10b86 to 134aaf9 Compare November 24, 2019 18:12

timhoffm reviewed Nov 24, 2019

View reviewed changes

QuLogic modified the milestones: v3.3.0, v3.4.0 May 1, 2020

jklymak added the status: needs rebase label Jul 15, 2020

jklymak marked this pull request as draft August 24, 2020 14:20

QuLogic modified the milestones: v3.4.0, v3.5.0 Jan 21, 2021

QuLogic modified the milestones: v3.5.0, v3.6.0 Aug 23, 2021

timhoffm modified the milestones: v3.6.0, unassigned Apr 30, 2022

story645 modified the milestones: unassigned, needs sorting Oct 6, 2022

dstansby mentioned this pull request Jan 26, 2023

Caching figures generated by plot directive #25091

Closed

6 tasks

dstansby closed this Jan 30, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Plot directive preserve #10149

Plot directive preserve #10149

r-barnes commented Jan 3, 2018

tacaswell commented Jan 3, 2018

jklymak Jan 3, 2018

r-barnes Jan 3, 2018

r-barnes Jan 3, 2018

jklymak Jan 3, 2018 •

edited

Loading

r-barnes Jan 3, 2018

r-barnes commented Jan 22, 2018

jklymak commented Jul 24, 2019

timhoffm commented Jul 24, 2019

tacaswell left a comment

tacaswell Aug 11, 2019

tacaswell commented Aug 12, 2019

anntzer left a comment

timhoffm commented Nov 24, 2019

timhoffm left a comment

timhoffm Nov 24, 2019

timhoffm Nov 24, 2019

dstansby commented Jan 30, 2023

		@@ -0,0 +1,61 @@
		Plot Directive `outname` and `plot_preserve_dir`

Plot directive preserve #10149

Plot directive preserve #10149

Conversation

r-barnes commented Jan 3, 2018

PR Summary

The :outname: property

The plot_preserve_dir configuration value

PR Checklist

tacaswell commented Jan 3, 2018

jklymak Jan 3, 2018

Choose a reason for hiding this comment

r-barnes Jan 3, 2018

Choose a reason for hiding this comment

r-barnes Jan 3, 2018

Choose a reason for hiding this comment

jklymak Jan 3, 2018 • edited Loading

Choose a reason for hiding this comment

r-barnes Jan 3, 2018

Choose a reason for hiding this comment

r-barnes commented Jan 22, 2018

jklymak commented Jul 24, 2019

timhoffm commented Jul 24, 2019

tacaswell left a comment

Choose a reason for hiding this comment

tacaswell Aug 11, 2019

Choose a reason for hiding this comment

tacaswell commented Aug 12, 2019

anntzer left a comment

Choose a reason for hiding this comment

timhoffm commented Nov 24, 2019

timhoffm left a comment

Choose a reason for hiding this comment

timhoffm Nov 24, 2019

Choose a reason for hiding this comment

timhoffm Nov 24, 2019

Choose a reason for hiding this comment

dstansby commented Jan 30, 2023

The `:outname:` property

The `plot_preserve_dir` configuration value

jklymak Jan 3, 2018 •

edited

Loading