Error in the plot directive if the plot file already exists

asmeurer · asmeurer · commit 4df7c14c8662 · 2024-05-08T15:16:55.000-06:00
Previously one plot would just silently overwrite the other, leading to
confusing output where both directives show the plot from the one that was
executed last.
diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py
@@ -53,8 +53,7 @@
     the RST document if no script is provided. The string can include the
     format ``{counter}`` to use an incremented counter. For example,
     ``'plot-{counter}'`` will create files like ``plot-1.png``, ``plot-2.png``,
-    and so on. If the ``{counter}`` is not provided, two plots with the same
-    output-base-name may overwrite each other.
+    and so on.
 
 ``:format:`` : {'python', 'doctest'}
     The format of the input.  If unset, the format is auto-detected.
@@ -98,8 +97,11 @@
 The plot directive has the following configuration options:
 
 plot_output_base_name
-    Default value for the output-base-name option (default is to use the name
-    of the input script, or the name of the RST file if no script is provided)
+    Default value for the output-base-name option. It's recommended to the
+    format string ``{counter}`` (for example, ``'plot-{counter}'``) so that
+    multiple plots in the same document will not conflict with each other.
+    (default is to use the name of the input script, or the name of the RST
+    file if no script is provided)
 
 plot_include_source
     Default value for the include-source option (default: False).
@@ -714,13 +716,17 @@ def render_figures(code, code_path, output_dir, output_base, context,
 
             for fmt, dpi in formats:
                 try:
+                    if os.path.exists(img.filename(fmt)):
+                        raise PlotError('file %s already exists. You may need to set output-base-name to something else.' % img.filename(fmt))
                     figman.canvas.figure.savefig(img.filename(fmt), dpi=dpi)
                     if fmt == formats[0][0] and config.plot_srcset:
                         # save a 2x, 3x etc version of the default...
                         srcset = _parse_srcset(config.plot_srcset)
                         for mult, suffix in srcset.items():
                             fm = f'{suffix}.{fmt}'
                             img.formats.append(fm)
+                            if os.path.exists(img.filename(fm)):
+                                raise PlotError('file %s already exists. You may need to set output-base-name to something else.' % img.filename(fmt))
                             figman.canvas.figure.savefig(img.filename(fm),
                                                          dpi=int(dpi * mult))
                 except Exception as err:
