From b8c5559adeaf626d289d5c4176a6d0cda33faf59 Mon Sep 17 00:00:00 2001 From: Richard Barnes Date: Wed, 3 Jan 2018 13:20:27 -0600 Subject: [PATCH 01/13] Added `:outname:` option and `plot_preserve_dir` configuration value --- lib/matplotlib/sphinxext/plot_directive.py | 65 ++++++++++++++++++++-- 1 file changed, 61 insertions(+), 4 deletions(-) diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py index 31dc1a6ff414..02be77772526 100644 --- a/lib/matplotlib/sphinxext/plot_directive.py +++ b/lib/matplotlib/sphinxext/plot_directive.py @@ -70,10 +70,18 @@ If specified, the code block will be run, but no figures will be inserted. This is usually useful with the ``:context:`` option. + 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 unique across + the generated documentation. + Additionally, this directive supports all of the options of the `image` directive, except for *target* (since plot will add its own target). These include `alt`, `height`, `width`, `scale`, `align` and `class`. + + Configuration options --------------------- @@ -129,12 +137,23 @@ plot_template Provide a customized template for preparing restructured text. + + plot_preserve_dir + Files with outnames are copied to this directory and files in this + directory are copied back from into the build directory prior to the + build beginning. """ import contextlib from io import StringIO import itertools import os +import sys +import shutil +import io +import re +import textwrap +import glob from os.path import relpath from pathlib import Path import re @@ -157,8 +176,12 @@ __version__ = 2 +#Outnames must be unique. This variable stores the outnames that +#have been seen so we can guarantee this and warn the user if a +#duplicate is encountered. +outname_list = set() -# ----------------------------------------------------------------------------- +#------------------------------------------------------------------------------ # Registration hook # ----------------------------------------------------------------------------- @@ -252,6 +275,7 @@ class PlotDirective(Directive): 'context': _option_context, 'nofigs': directives.flag, 'encoding': directives.encoding, + 'outname': str } def run(self): @@ -276,6 +300,7 @@ def setup(app): app.add_config_value('plot_apply_rcparams', False, True) app.add_config_value('plot_working_directory', None, True) app.add_config_value('plot_template', None, True) + app.add_config_value('plot_preserve_dir', '', True) app.connect('doctree-read', mark_plot_labels) @@ -519,7 +544,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=''): """ Run a pyplot script and save the images in *output_dir*. @@ -610,7 +635,10 @@ def render_figures(code, code_path, output_dir, output_base, context, for fmt, dpi in formats: try: figman.canvas.figure.savefig(img.filename(fmt), dpi=dpi) - except Exception: + if config.plot_preserve_dir and outname: + print("Preserving '{0}' into '{1}'".format(img.filename(format), config.plot_preserve_dir)) + shutil.copy2(img.filename(format), config.plot_preserve_dir) + except Exception as err: raise PlotError(traceback.format_exc()) img.formats.append(fmt) @@ -637,6 +665,20 @@ def run(arguments, content, options, state_machine, state, lineno): rst_file = document.attributes['source'] rst_dir = os.path.dirname(rst_file) + #Get output name of the images, if the option was provided + outname = options.get('outname', '') + + #Ensure that the outname is unique, otherwise copied images will + #not be what user expects + if outname in outname_list: + raise Exception("The outname '{0}' is not unique!".format(outname)) + else: + outname_list.add(outname) + + if config.plot_preserve_dir: + #Ensure `preserve_dir` ends with a slash, otherwise `copy2` will misbehave + config.plot_preserve_dir = os.path.join(config.plot_preserve_dir, '') + if len(arguments): if not config.plot_basedir: source_file_name = os.path.join(setup.app.builder.srcdir, @@ -672,6 +714,11 @@ def run(arguments, content, options, state_machine, state, lineno): else: source_ext = '' + #outname, if present, overrides output_base, but preserve + #numbering of multi-figure code snippets + if outname: + output_base = re.sub('^[^-]*', outname, output_base) + # ensure that LaTeX includegraphics doesn't choke in foo.bar.pdf filenames output_base = output_base.replace('.', '-') @@ -718,6 +765,15 @@ def run(arguments, content, options, state_machine, state, lineno): build_dir_link = build_dir source_link = dest_dir_link + '/' + output_base + source_ext + #If we previously preserved copies of the generated figures + #this copies them into the build directory so that they will + #not be remade + if config.plot_preserve_dir and outname: + outfiles = glob.glob(os.path.join(config.plot_preserve_dir,outname) + '*') + for of in outfiles: + print("Copying preserved copy of '{0}' into '{1}'".format(of, build_dir)) + shutil.copy2(of, build_dir) + # make figures try: results = render_figures(code, @@ -728,7 +784,8 @@ def run(arguments, content, options, state_machine, state, lineno): function_name, config, context_reset=context_opt == 'reset', - close_figs=context_opt == 'close-figs') + close_figs=context_opt == 'close-figs', + outname = outname) errors = [] except PlotError as err: reporter = state.memo.reporter From d4c41ff7a1e19c732e4d41c74167de4f58b7063f Mon Sep 17 00:00:00 2001 From: Richard Barnes Date: Wed, 3 Jan 2018 13:39:41 -0600 Subject: [PATCH 02/13] Added What's New for plot directive changes --- .../2018_12_03_sphinx_plot_preserve.rst | 56 +++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 doc/users/next_whats_new/2018_12_03_sphinx_plot_preserve.rst 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 new file mode 100644 index 000000000000..925903b64b69 --- /dev/null +++ b/doc/users/next_whats_new/2018_12_03_sphinx_plot_preserve.rst @@ -0,0 +1,56 @@ +Plot Directive `outname` and `plot_preserve_dir` +---------------------------------------------------- + +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 address 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. + From 69356da3b43add8483f404a534dc57866dfdbc88 Mon Sep 17 00:00:00 2001 From: Richard Barnes Date: Wed, 3 Jan 2018 13:51:25 -0600 Subject: [PATCH 03/13] Futzing with PEP8 whitespace stuff. --- lib/matplotlib/sphinxext/plot_directive.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py index 02be77772526..ea6dea72a41e 100644 --- a/lib/matplotlib/sphinxext/plot_directive.py +++ b/lib/matplotlib/sphinxext/plot_directive.py @@ -785,7 +785,7 @@ def run(arguments, content, options, state_machine, state, lineno): config, context_reset=context_opt == 'reset', close_figs=context_opt == 'close-figs', - outname = outname) + outname=outname) errors = [] except PlotError as err: reporter = state.memo.reporter From 8b477a42736ab842a76957abe2d9b6f155b2296f Mon Sep 17 00:00:00 2001 From: Richard Barnes Date: Wed, 3 Jan 2018 14:09:57 -0600 Subject: [PATCH 04/13] Fix grammer --- doc/users/next_whats_new/2018_12_03_sphinx_plot_preserve.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 925903b64b69..283fb9918215 100644 --- 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 @@ -25,7 +25,7 @@ generated imagery to be used on services like ReadTheDocs. The `:outname:` property ~~~~~~~~~~~~~~~~~~~~~~~~ -These problems are address through two new features in the plot directive. The +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:: From fddd4900de4df1ba46393e2f2cde23c662515b64 Mon Sep 17 00:00:00 2001 From: Richard Barnes Date: Wed, 3 Jan 2018 15:16:59 -0600 Subject: [PATCH 05/13] Fix bug with adding null string to outname_list --- lib/matplotlib/sphinxext/plot_directive.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py index ea6dea72a41e..7d4e27968598 100644 --- a/lib/matplotlib/sphinxext/plot_directive.py +++ b/lib/matplotlib/sphinxext/plot_directive.py @@ -670,7 +670,7 @@ def run(arguments, content, options, state_machine, state, lineno): #Ensure that the outname is unique, otherwise copied images will #not be what user expects - if outname in outname_list: + if outname and outname in outname_list: raise Exception("The outname '{0}' is not unique!".format(outname)) else: outname_list.add(outname) From 872faa1cb9390112212ace10f653cd4672f1ad99 Mon Sep 17 00:00:00 2001 From: Richard Barnes Date: Wed, 3 Jan 2018 15:19:07 -0600 Subject: [PATCH 06/13] Added a test of `:outname:` --- lib/matplotlib/tests/tinypages/some_plots.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/lib/matplotlib/tests/tinypages/some_plots.rst b/lib/matplotlib/tests/tinypages/some_plots.rst index 615908b0107f..7aed2881898a 100644 --- a/lib/matplotlib/tests/tinypages/some_plots.rst +++ b/lib/matplotlib/tests/tinypages/some_plots.rst @@ -126,4 +126,11 @@ Plot 16 uses a specific function in a file with plot commands: .. plot:: range6.py range6 +Plot 17 has an outname +.. plot:: + :context: close-figs + :outname: plot17out + + plt.figure() + plt.plot(range(4)) From 0ee71f09861907b3385f695edfccc6c7cc0cec6b Mon Sep 17 00:00:00 2001 From: Richard Barnes Date: Wed, 3 Jan 2018 15:41:54 -0600 Subject: [PATCH 07/13] Examples of using rst need to be code blocks --- doc/users/next_whats_new/2018_12_03_sphinx_plot_preserve.rst | 4 ++++ 1 file changed, 4 insertions(+) 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 index 283fb9918215..ee2c6006218b 100644 --- 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 @@ -4,6 +4,8 @@ Plot Directive `outname` and `plot_preserve_dir` The Sphinx plot directive can be used to automagically generate figures for documentation like so: +.. code-block:: rst + .. plot:: import matplotlib.pyplot as plt @@ -28,6 +30,8 @@ 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: +.. code-block:: rst + .. plot:: :outname: stinkbug_plot From 082298e3330f9193382673eadebddd874073128c Mon Sep 17 00:00:00 2001 From: Richard Barnes Date: Wed, 3 Jan 2018 15:45:20 -0600 Subject: [PATCH 08/13] Use logging instead of print --- lib/matplotlib/sphinxext/plot_directive.py | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py index 7d4e27968598..337656e2e5d1 100644 --- a/lib/matplotlib/sphinxext/plot_directive.py +++ b/lib/matplotlib/sphinxext/plot_directive.py @@ -154,6 +154,7 @@ import re import textwrap import glob +import logging from os.path import relpath from pathlib import Path import re @@ -176,10 +177,12 @@ __version__ = 2 +_log = logging.getLogger(__name__) + #Outnames must be unique. This variable stores the outnames that #have been seen so we can guarantee this and warn the user if a #duplicate is encountered. -outname_list = set() +_outname_list = set() #------------------------------------------------------------------------------ # Registration hook @@ -636,7 +639,7 @@ def render_figures(code, code_path, output_dir, output_base, context, try: figman.canvas.figure.savefig(img.filename(fmt), dpi=dpi) if config.plot_preserve_dir and outname: - print("Preserving '{0}' into '{1}'".format(img.filename(format), config.plot_preserve_dir)) + _log.info("Preserving '{0}' into '{1}'".format(img.filename(format), config.plot_preserve_dir)) shutil.copy2(img.filename(format), config.plot_preserve_dir) except Exception as err: raise PlotError(traceback.format_exc()) @@ -670,10 +673,10 @@ def run(arguments, content, options, state_machine, state, lineno): #Ensure that the outname is unique, otherwise copied images will #not be what user expects - if outname and outname in outname_list: + if outname and outname in _outname_list: raise Exception("The outname '{0}' is not unique!".format(outname)) else: - outname_list.add(outname) + _outname_list.add(outname) if config.plot_preserve_dir: #Ensure `preserve_dir` ends with a slash, otherwise `copy2` will misbehave @@ -771,7 +774,7 @@ def run(arguments, content, options, state_machine, state, lineno): if config.plot_preserve_dir and outname: outfiles = glob.glob(os.path.join(config.plot_preserve_dir,outname) + '*') for of in outfiles: - print("Copying preserved copy of '{0}' into '{1}'".format(of, build_dir)) + _log.info("Copying preserved copy of '{0}' into '{1}'".format(of, build_dir)) shutil.copy2(of, build_dir) # make figures From 73858c1a702d164ee02c95b33b1950cea9aff66b Mon Sep 17 00:00:00 2001 From: Richard Barnes Date: Wed, 3 Jan 2018 17:07:10 -0600 Subject: [PATCH 09/13] Satisfy PEP8 checks --- lib/matplotlib/sphinxext/plot_directive.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py index 337656e2e5d1..f3a0d085a3c3 100644 --- a/lib/matplotlib/sphinxext/plot_directive.py +++ b/lib/matplotlib/sphinxext/plot_directive.py @@ -772,7 +772,7 @@ def run(arguments, content, options, state_machine, state, lineno): #this copies them into the build directory so that they will #not be remade if config.plot_preserve_dir and outname: - outfiles = glob.glob(os.path.join(config.plot_preserve_dir,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)) shutil.copy2(of, build_dir) From 74e9fbc06f2f6807c62c0c12a32c01b8bdc354f7 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Sun, 11 Aug 2019 20:29:28 -0400 Subject: [PATCH 10/13] FIX: issue with rebase due to re-naming of local variables --- lib/matplotlib/sphinxext/plot_directive.py | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py index f3a0d085a3c3..d00305b3c3ad 100644 --- a/lib/matplotlib/sphinxext/plot_directive.py +++ b/lib/matplotlib/sphinxext/plot_directive.py @@ -639,8 +639,11 @@ def render_figures(code, code_path, output_dir, output_base, context, try: figman.canvas.figure.savefig(img.filename(fmt), dpi=dpi) if config.plot_preserve_dir and outname: - _log.info("Preserving '{0}' into '{1}'".format(img.filename(format), config.plot_preserve_dir)) - shutil.copy2(img.filename(format), config.plot_preserve_dir) + _log.info( + "Preserving '{0}' into '{1}'".format( + img.filename(fmt), config.plot_preserve_dir)) + shutil.copy2(img.filename(fmt), + config.plot_preserve_dir) except Exception as err: raise PlotError(traceback.format_exc()) img.formats.append(fmt) From cd784160ec0889e73218c66f936b7f5d8b1b8631 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Sun, 11 Aug 2019 20:29:51 -0400 Subject: [PATCH 11/13] STY: fix line length and indentation issues --- lib/matplotlib/sphinxext/plot_directive.py | 30 ++++++++++++---------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py index d00305b3c3ad..27fa062e1e47 100644 --- a/lib/matplotlib/sphinxext/plot_directive.py +++ b/lib/matplotlib/sphinxext/plot_directive.py @@ -71,10 +71,10 @@ inserted. This is usually useful with the ``:context:`` option. 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 unique across - the generated documentation. + 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 + unique across the generated documentation. Additionally, this directive supports all of the options of the `image` directive, except for *target* (since plot will add its own target). These @@ -142,6 +142,7 @@ Files with outnames are copied to this directory and files in this directory are copied back from into the build directory prior to the build beginning. + """ import contextlib @@ -677,13 +678,14 @@ def run(arguments, content, options, state_machine, state, lineno): #Ensure that the outname is unique, otherwise copied images will #not be what user expects if outname and outname in _outname_list: - raise Exception("The outname '{0}' is not unique!".format(outname)) + raise Exception("The outname '{0}' is not unique!".format(outname)) else: - _outname_list.add(outname) + _outname_list.add(outname) if config.plot_preserve_dir: - #Ensure `preserve_dir` ends with a slash, otherwise `copy2` will misbehave - config.plot_preserve_dir = os.path.join(config.plot_preserve_dir, '') + # Ensure `preserve_dir` ends with a slash, otherwise `copy2` + # will misbehave + config.plot_preserve_dir = os.path.join(config.plot_preserve_dir, '') if len(arguments): if not config.plot_basedir: @@ -723,7 +725,7 @@ def run(arguments, content, options, state_machine, state, lineno): #outname, if present, overrides output_base, but preserve #numbering of multi-figure code snippets if outname: - output_base = re.sub('^[^-]*', outname, output_base) + output_base = re.sub('^[^-]*', outname, output_base) # ensure that LaTeX includegraphics doesn't choke in foo.bar.pdf filenames output_base = output_base.replace('.', '-') @@ -775,10 +777,12 @@ def run(arguments, content, options, state_machine, state, lineno): #this copies them into the build directory so that they will #not be remade 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)) - shutil.copy2(of, build_dir) + 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)) + shutil.copy2(of, build_dir) # make figures try: From 725f25d87d3175919faba198cd85ce849901a7ea Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Sun, 11 Aug 2019 20:40:35 -0400 Subject: [PATCH 12/13] STY: trim whitespace and add trailing comma --- lib/matplotlib/sphinxext/plot_directive.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py index 27fa062e1e47..cb7091b1bcbb 100644 --- a/lib/matplotlib/sphinxext/plot_directive.py +++ b/lib/matplotlib/sphinxext/plot_directive.py @@ -279,7 +279,7 @@ class PlotDirective(Directive): 'context': _option_context, 'nofigs': directives.flag, 'encoding': directives.encoding, - 'outname': str + 'outname': str, } def run(self): @@ -304,7 +304,7 @@ def setup(app): app.add_config_value('plot_apply_rcparams', False, True) app.add_config_value('plot_working_directory', None, True) app.add_config_value('plot_template', None, True) - app.add_config_value('plot_preserve_dir', '', True) + app.add_config_value('plot_preserve_dir', '', True) app.connect('doctree-read', mark_plot_labels) From 134aaf966d48b2d85e35911119ef871d0ff7bf70 Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Sun, 24 Nov 2019 19:10:26 +0100 Subject: [PATCH 13/13] Fix doc style --- .../2018_12_03_sphinx_plot_preserve.rst | 33 ++++++++++--------- lib/matplotlib/sphinxext/plot_directive.py | 19 +++++------ 2 files changed, 26 insertions(+), 26 deletions(-) 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 index ee2c6006218b..396c481a8815 100644 --- 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 @@ -24,11 +24,12 @@ 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 -~~~~~~~~~~~~~~~~~~~~~~~~ +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: +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: .. code-block:: rst @@ -41,20 +42,20 @@ first is the introduction of the `:outname:` property. It is used like so: 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. +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 code snippets. -The `plot_preserve_dir` configuration value -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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. +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 +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. - diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py index cb7091b1bcbb..f1f8fdda87c9 100644 --- a/lib/matplotlib/sphinxext/plot_directive.py +++ b/lib/matplotlib/sphinxext/plot_directive.py @@ -140,8 +140,8 @@ plot_preserve_dir Files with outnames are copied to this directory and files in this - directory are copied back from into the build directory prior to the - build beginning. + directory are copied back into the build directory prior to the build + beginning. """ @@ -672,11 +672,11 @@ def run(arguments, content, options, state_machine, state, lineno): rst_file = document.attributes['source'] rst_dir = os.path.dirname(rst_file) - #Get output name of the images, if the option was provided + # Get output name of the images, if the option was provided outname = options.get('outname', '') - #Ensure that the outname is unique, otherwise copied images will - #not be what user expects + # Ensure that the outname is unique, otherwise copied images will + # not be what user expects if outname and outname in _outname_list: raise Exception("The outname '{0}' is not unique!".format(outname)) else: @@ -722,8 +722,8 @@ def run(arguments, content, options, state_machine, state, lineno): else: source_ext = '' - #outname, if present, overrides output_base, but preserve - #numbering of multi-figure code snippets + # outname, if present, overrides output_base, but preserve + # numbering of multi-figure code snippets if outname: output_base = re.sub('^[^-]*', outname, output_base) @@ -773,9 +773,8 @@ def run(arguments, content, options, state_machine, state, lineno): build_dir_link = build_dir source_link = dest_dir_link + '/' + output_base + source_ext - #If we previously preserved copies of the generated figures - #this copies them into the build directory so that they will - #not be remade + # If we previously preserved copies of the generated figures this copies + # them into the build directory so that they will not be remade. if config.plot_preserve_dir and outname: outfiles = glob.glob( os.path.join(config.plot_preserve_dir, outname) + '*')