Adds plot_skip_execution config to temporarily disable plot_directive. (#31270)

billbrod · tacaswell · web-flow · commit a94275af4216 · 2026-05-22T13:58:44.000+02:00
* squashed commit adding plot_skip_execution config

* MNT: will be in mpl 3.12

---------

Co-authored-by: Thomas A Caswell &lt;tcaswell@gmail.com&gt;
diff --git a/doc/release/next_whats_new/plot_skip_execution.rst b/doc/release/next_whats_new/plot_skip_execution.rst
@@ -0,0 +1,11 @@
+New config option for ``matplotlib.sphinxext.plot_directive``: ``plot_skip_execution``
+--------------------------------------------------------------------------------------
+
+This configuration option allows users to temporarily skip the execution of all
+plot directives, not running the code or generating the plots. It is intended to
+be used during development to speed up building documentation that contains many
+plot directives.
+
+It can be temporarily enabled from the command line by passing ``-D
+plot_skip_execution=1`` to ``sphinx-build``, e.g.,: ``make html O="-D
+plot_skip_execution=1"``.
diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py
@@ -162,6 +162,12 @@
     The plot_srcset option is incompatible with *singlehtml* builds, and an
     error will be raised.
 
+plot_skip_execution
+    If True, will not run any plot directives. Code, captions, etc. will all
+    still be rendered, but no plots will be created.
+
+    .. versionadded:: 3.12
+
 Notes on how it works
 ---------------------
 
@@ -323,6 +329,7 @@ def setup(app):
     app.add_config_value('plot_working_directory', None, True)
     app.add_config_value('plot_template', None, True)
     app.add_config_value('plot_srcset', [], True)
+    app.add_config_value('plot_skip_execution', False, True)
     app.connect('doctree-read', mark_plot_labels)
     app.add_css_file('plot_directive.css')
     app.connect('build-finished', _copy_css_file)
@@ -925,16 +932,19 @@ def run(arguments, content, options, state_machine, state, lineno):
 
     # make figures
     try:
-        results = render_figures(code=code,
-                                 code_path=source_file_name,
-                                 output_dir=build_dir,
-                                 output_base=output_base,
-                                 context=keep_context,
-                                 function_name=function_name,
-                                 config=config,
-                                 context_reset=context_opt == 'reset',
-                                 close_figs=context_opt == 'close-figs',
-                                 code_includes=source_file_includes)
+        if config.plot_skip_execution:
+            results = [(code, [])]
+        else:
+            results = render_figures(code=code,
+                                     code_path=source_file_name,
+                                     output_dir=build_dir,
+                                     output_base=output_base,
+                                     context=keep_context,
+                                     function_name=function_name,
+                                     config=config,
+                                     context_reset=context_opt == 'reset',
+                                     close_figs=context_opt == 'close-figs',
+                                     code_includes=source_file_includes)
         errors = []
     except PlotError as err:
         reporter = state.memo.reporter
diff --git a/lib/matplotlib/tests/test_sphinxext.py b/lib/matplotlib/tests/test_sphinxext.py
@@ -269,3 +269,51 @@ def plot_file(num, suff=''):
     st = ('srcset="../_images/nestedpage2-index-2.png, '
           '../_images/nestedpage2-index-2.2x.png 2.00x"')
     assert st in (html_dir / 'nestedpage2/index.html').read_text(encoding='utf-8')
+
+
+def test_plot_skip_execution(tmp_path):
+    # test that modifying plot_exclude_patterns in config leads to skipping files
+    shutil.copyfile(tinypages / 'conf.py', tmp_path / 'conf.py')
+    shutil.copytree(tinypages / '_static', tmp_path / '_static')
+    shutil.copyfile(tinypages / 'range4.py', tmp_path / 'range4.py')
+    shutil.copyfile(tinypages / 'range6.py', tmp_path / 'range6.py')
+
+    html_dir = tmp_path / '_build' / 'html'
+    img_dir = html_dir / '_images'
+    doctree_dir = tmp_path / 'doctrees'
+
+    (tmp_path / 'index.rst').write_text("""
+.. plot::
+
+    plt.plot(range(2))
+
+.. toctree::
+
+    script_func
+    script_nofunc
+""")
+    (tmp_path / 'script_func.rst').write_text("""
+##########
+Some plots
+##########
+
+.. plot:: range6.py range6
+
+.. plot:: range6.py range10
+""")
+    (tmp_path / 'script_nofunc.rst').write_text("""
+##########
+Some plots
+##########
+
+.. plot:: range4.py
+""")
+
+    # Build the pages with warnings turned into errors
+    build_sphinx_html(tmp_path, doctree_dir, html_dir,
+                      extra_args=["-D", "plot_skip_execution=1"])
+
+    assert not (img_dir / "index-1.png").exists()
+    assert not (img_dir / "range6_range6.png").exists()
+    assert not (img_dir / "range6_range10.png").exists()
+    assert not (img_dir / "range4.png").exists()
