Remove {counter} from output-base-name and remove the global config

The idea of allowing the use of the counter for custom base names is flawed
because the counter would always be incremented even for custom names that
don't use it. Also, the global base name is difficult to get working because
we don't have a good global view of the plots to create a counter, especially
in the case of partial rebuilds.

Instead, we just simplify things by just allowing setting a custom-base-name.
If two plot directives use the same custom-base-name, then one will end up
overwriting the other (I'm still looking into whether it's possible to at
least detect this and give an error).

Author: asmeurer

lib/matplotlib/sphinxext/plot_directive.py

@@ -50,10 +50,7 @@
 ``:output-base-name:`` : str
     The base name (without the extension) of the outputted image files. The
     default is to use the same name as the input script, or the name of
-    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
+    the RST document if no script is provided. Note: two plots with the same
     output-base-name may overwrite each other.
 
 ``:format:`` : {'python', 'doctest'}
@@ -97,10 +94,6 @@
 
 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)
-
 plot_include_source
     Default value for the include-source option (default: False).
 
@@ -313,7 +306,6 @@ def setup(app):
     app.add_config_value('plot_pre_code', None, True)
     app.add_config_value('plot_include_source', False, True)
     app.add_config_value('plot_html_show_source_link', True, True)
-    app.add_config_value('plot_output_base_name', None, True)
     app.add_config_value('plot_formats', ['png', 'hires.png', 'pdf'], True)
     app.add_config_value('plot_basedir', None, True)
     app.add_config_value('plot_html_show_formats', True, True)
@@ -749,7 +741,7 @@ def run(arguments, content, options, state_machine, state, lineno):
 
     options.setdefault('include-source', config.plot_include_source)
     options.setdefault('show-source-link', config.plot_html_show_source_link)
-    options.setdefault('output-base-name', config.plot_output_base_name)
+    options.setdefault('output-base-name', None)
 
     if 'class' in options:
         # classes are parsed into a list of string, and output by simply
@@ -798,12 +790,12 @@ def run(arguments, content, options, state_machine, state, lineno):
     else:
         source_file_name = rst_file
         code = textwrap.dedent("\n".join(map(str, content)))
-        counter = document.attributes.get('_plot_counter', 0) + 1
-        document.attributes['_plot_counter'] = counter
         base, ext = os.path.splitext(os.path.basename(source_file_name))
         if options['output-base-name']:
-            output_base = options['output-base-name'].format(counter=counter)
+            output_base = options['output-base-name']
         else:
+            counter = document.attributes.get('_plot_counter', 0) + 1
+            document.attributes['_plot_counter'] = counter
             output_base = '%s-%d.py' % (base, counter)
         function_name = None
         caption = options.get('caption', '')

lib/matplotlib/tests/test_sphinxext.py

@@ -97,9 +97,9 @@ def plot_directive_file(num):
     assert filecmp.cmp(range_6, plot_file(17))
     # plot 22 is from the range6.py file again, but a different function
     assert filecmp.cmp(range_10, img_dir / 'range6_range10.png')
-    # plots 23 and 24 use a custom base name with {counter}
-    assert filecmp.cmp(range_4, img_dir / 'custom-base-name-18.png')
-    assert filecmp.cmp(range_6, img_dir / 'custom-base-name-19.png')
+    # plots 23 and 24 use a custom base name
+    assert filecmp.cmp(range_4, img_dir / 'custom-base-name-1.png')
+    assert filecmp.cmp(range_6, img_dir / 'custom-base-name-2.png')
 
     # Modify the included plot
     contents = (tmp_path / 'included_plot_21.rst').read_bytes()

lib/matplotlib/tests/tinypages/some_plots.rst

@@ -175,14 +175,14 @@ Plot 22 uses a different specific function in a file with plot commands:
 
 .. plot:: range6.py range10
 
-Plots 23 and 24 use output-base-name with a {counter}.
+Plots 23 and 24 use output-base-name.
 
 .. plot::
-   :output-base-name: custom-base-name-{counter}
+   :output-base-name: custom-base-name-1
 
    plt.plot(range(4))
 
 .. plot::
-   :output-base-name: custom-base-name-{counter}
+   :output-base-name: custom-base-name-2
 
    plt.plot(range(6))