matplotlib · timhoffm · Jun 16, 2025 · May 8, 2024 · May 9, 2024 · Oct 11, 2024
diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py
@@ -47,6 +47,12 @@
 
 The ``.. plot::`` directive supports the following options:
 
+``:image-basename:`` : 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 image-basename for each
+    plot directive must be unique.
+
 ``:format:`` : {'python', 'doctest'}
     The format of the input.  If unset, the format is auto-detected.
 
@@ -165,6 +171,7 @@
 and *TEMPLATE_SRCSET*.
 """
 
+from collections import defaultdict
 import contextlib
 import doctest
 from io import StringIO
@@ -182,6 +189,7 @@
 from docutils.parsers.rst.directives.images import Image
 import jinja2  # Sphinx dependency.
 
+from sphinx.environment.collectors import EnvironmentCollector
 from sphinx.errors import ExtensionError
 
 import matplotlib
@@ -265,6 +273,7 @@
         'scale': directives.nonnegative_int,
         'align': Image.align,
         'class': directives.class_option,
+        'image-basename': directives.unchanged,
         'include-source': _option_boolean,
         'show-source-link': _option_boolean,
         'format': _option_format,
@@ -312,9 +321,35 @@
     app.connect('build-finished', _copy_css_file)
     metadata = {'parallel_read_safe': True, 'parallel_write_safe': True,
                 'version': matplotlib.__version__}
+    app.connect('builder-inited', init_filename_registry)
+    app.add_env_collector(_FilenameCollector)
     return metadata
 
 
+# -----------------------------------------------------------------------------
+# Handle Duplicate Filenames
+# -----------------------------------------------------------------------------
+
+def init_filename_registry(app):
+    env = app.builder.env
+    if not hasattr(env, 'mpl_plot_image_basenames'):
+        env.mpl_plot_image_basenames = defaultdict(set)
+
+
+class _FilenameCollector(EnvironmentCollector):
+    def process_doc(self, app, doctree):
+        pass
+
+    def clear_doc(self, app, env, docname):
+        if docname in env.mpl_plot_image_basenames:
+            del env.mpl_plot_image_basenames[docname]
+
+    def merge_other(self, app, env, docnames, other):
+        for docname in other.mpl_plot_image_basenames:
+            env.mpl_plot_image_basenames[docname].update(
+                other.mpl_plot_image_basenames[docname])
+
+
 # -----------------------------------------------------------------------------
 # Doctest handling
 # -----------------------------------------------------------------------------
@@ -600,6 +635,27 @@
     return srcset
 
 
+def check_output_base_name(env, output_base):
+    docname = env.docname
+
+    if '.' in output_base or '/' in output_base:
+        raise PlotError(
+            f"The image-basename '{output_base}' is invalid. "
+            f"It must not contain dots or slashes.")
+
+    for d in env.mpl_plot_image_basenames:
+        if output_base in env.mpl_plot_image_basenames[d]:
+            if d == docname:
+                raise PlotError(
+                    f"The image-basename "
+                    f"{output_base}' is used multiple times.")
+            raise PlotError(f"The image-basename "
+                            f"'{output_base}' is used multiple times "
+                            f"(it is also used in {env.doc2path(d)}).")
+
+    env.mpl_plot_image_basenames[docname].add(output_base)
+
+
 def render_figures(code, code_path, output_dir, output_base, context,
                    function_name, config, context_reset=False,
                    close_figs=False,
@@ -723,6 +779,7 @@
 def run(arguments, content, options, state_machine, state, lineno):
     document = state_machine.document
     config = document.settings.env.config
+    env = document.settings.env
     nofigs = 'nofigs' in options
 
     if config.plot_srcset and setup.app.builder.name == 'singlehtml':
@@ -734,6 +791,7 @@
 
     options.setdefault('include-source', config.plot_include_source)
     options.setdefault('show-source-link', config.plot_html_show_source_link)
+    options.setdefault('image-basename', None)
 
     if 'class' in options:
         # classes are parsed into a list of string, and output by simply
@@ -775,14 +833,22 @@
             function_name = None
 
         code = Path(source_file_name).read_text(encoding='utf-8')
-        output_base = os.path.basename(source_file_name)
+        if options['image-basename']:
+            output_base = options['image-basename']
+            check_output_base_name(env, output_base)
+        else:
+            output_base = os.path.basename(source_file_name)
     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))
-        output_base = '%s-%d.py' % (base, counter)
+        if options['image-basename']:
+            output_base = options['image-basename']
+            check_output_base_name(env, output_base)
+        else:
+            base, ext = os.path.splitext(os.path.basename(source_file_name))
+            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', '')
 

diff --git a/lib/matplotlib/tests/test_sphinxext.py b/lib/matplotlib/tests/test_sphinxext.py
@@ -96,6 +96,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 basename
+    assert filecmp.cmp(range_6, img_dir / 'custom-basename-6.png')
+    assert filecmp.cmp(range_4, img_dir / 'custom-basename-4.png')
 
     # Modify the included plot
     contents = (tmp_path / 'included_plot_21.rst').read_bytes()

diff --git a/lib/matplotlib/tests/tinypages/some_plots.rst b/lib/matplotlib/tests/tinypages/some_plots.rst
@@ -174,3 +174,13 @@ Plot 21 is generated via an include directive:
 Plot 22 uses a different specific function in a file with plot commands:
 
 .. plot:: range6.py range10
+
+Plots 23 and 24 use image-basename.
+
+.. plot::
+   :image-basename: custom-basename-6
+
+   plt.plot(range(6))
+
+.. plot:: range4.py
+   :image-basename: custom-basename-4