Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions doc/release/next_whats_new/plot_skip_execution.rst
Original file line number Diff line number Diff line change
@@ -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"``.
30 changes: 20 additions & 10 deletions lib/matplotlib/sphinxext/plot_directive.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
---------------------

Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down
48 changes: 48 additions & 0 deletions lib/matplotlib/tests/test_sphinxext.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Comment thread
billbrod marked this conversation as resolved.
Resolved
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()
Loading