Add :shows-source-link: option to Sphinx plot directive

lpsinger · lpsinger · commit 9c5a5dc8e373 · 2022-10-18T15:12:52.000-04:00
The Sphinx plot directive (`.. plot::`) now supports a
`:show-source-link` option to show or hide the link to the source
for each plot. The default is set using the
`plot_html_show_source_link` variable in `conf.py` (which itself
defaults to True).
diff --git a/doc/users/next_whats_new/show_source_links_directive_option.rst b/doc/users/next_whats_new/show_source_links_directive_option.rst
@@ -0,0 +1,7 @@
+Source links can be shown or hidden for each Sphinx plot directive
+------------------------------------------------------------------
+The :doc:`Sphinx plot directive </api/sphinxext_plot_directive>`
+(``.. plot::``) now supports a ``:show-source-link:`` option to show or hide
+the link to the source for each plot. The default is set using the
+``plot_html_show_source_link`` variable in :file:`conf.py` (which itself
+defaults to True).
diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py
@@ -55,6 +55,11 @@
         the ``plot_include_source`` variable in :file:`conf.py` (which itself
         defaults to False).
 
+    ``:show-source-link:`` : bool
+        Whether to show a link to the source in HTML. The default can be
+        changed using the ``plot_html_show_source_link`` variable in
+        :file:`conf.py` (which itself defaults to True).
+
     ``:encoding:`` : str
         If this source file is in a non-UTF8 or non-ASCII encoding, the
         encoding must be specified using the ``:encoding:`` option.  The
@@ -245,6 +250,7 @@ class PlotDirective(Directive):
         'align': Image.align,
         'class': directives.class_option,
         'include-source': _option_boolean,
+        'show-source-link': _option_boolean,
         'format': _option_format,
         'context': _option_context,
         'nofigs': directives.flag,
@@ -666,6 +672,7 @@ def run(arguments, content, options, state_machine, state, lineno):
     default_fmt = formats[0][0]
 
     options.setdefault('include-source', config.plot_include_source)
+    options.setdefault('show-source-link', config.plot_html_show_source_link)
     if 'class' in options:
         # classes are parsed into a list of string, and output by simply
         # printing the list, abusing the fact that RST guarantees to strip
@@ -832,7 +839,7 @@ def run(arguments, content, options, state_machine, state, lineno):
 
         # Not-None src_link signals the need for a source link in the generated
         # html
-        if j == 0 and config.plot_html_show_source_link:
+        if j == 0 and options['show-source-link']:
             src_link = source_link
         else:
             src_link = None
@@ -866,7 +873,7 @@ def run(arguments, content, options, state_machine, state, lineno):
                     shutil.copyfile(fn, destimg)
 
     # copy script (if necessary)
-    if config.plot_html_show_source_link:
+    if options['show-source-link']:
         Path(dest_dir, output_base + source_ext).write_text(
             doctest.script_from_examples(code)
             if source_file_name == rst_file and is_doctest
diff --git a/lib/matplotlib/tests/test_sphinxext.py b/lib/matplotlib/tests/test_sphinxext.py
@@ -122,6 +122,56 @@ def test_plot_html_show_source_link(tmpdir):
     assert "index-1.py" not in [p.name for p in html_dir2.iterdir()]
 
 
+def test_show_source_link_true(tmpdir):
+    source_dir = Path(tmpdir) / 'src'
+    source_dir.mkdir()
+    parent = Path(__file__).parent
+    shutil.copyfile(parent / 'tinypages/conf.py', source_dir / 'conf.py')
+    shutil.copytree(parent / 'tinypages/_static', source_dir / '_static')
+    doctree_dir = source_dir / 'doctrees'
+    (source_dir / 'index.rst').write_text("""
+.. plot::
+    :show-source-link: true
+
+    plt.plot(range(2))
+""")
+    # Make sure source scripts are created by default
+    html_dir1 = source_dir / '_build' / 'html1'
+    build_sphinx_html(source_dir, doctree_dir, html_dir1)
+    assert "index-1.py" in [p.name for p in html_dir1.iterdir()]
+    # Make sure source scripts are still created when
+    # plot_html_show_source_link` is False
+    html_dir2 = source_dir / '_build' / 'html2'
+    build_sphinx_html(source_dir, doctree_dir, html_dir2,
+                      extra_args=['-D', 'plot_html_show_source_link=0'])
+    assert "index-1.py" in [p.name for p in html_dir1.iterdir()]
+
+
+def test_show_source_link_false(tmpdir):
+    source_dir = Path(tmpdir) / 'src'
+    source_dir.mkdir()
+    parent = Path(__file__).parent
+    shutil.copyfile(parent / 'tinypages/conf.py', source_dir / 'conf.py')
+    shutil.copytree(parent / 'tinypages/_static', source_dir / '_static')
+    doctree_dir = source_dir / 'doctrees'
+    (source_dir / 'index.rst').write_text("""
+.. plot::
+    :show-source-link: false
+
+    plt.plot(range(2))
+""")
+    # Make sure source scripts are NOT created
+    html_dir1 = source_dir / '_build' / 'html1'
+    build_sphinx_html(source_dir, doctree_dir, html_dir1)
+    assert "index-1.py" not in [p.name for p in html_dir1.iterdir()]
+    # Make sure source scripts are still NOT created when
+    # plot_html_show_source_link` is False
+    html_dir2 = source_dir / '_build' / 'html2'
+    build_sphinx_html(source_dir, doctree_dir, html_dir2,
+                      extra_args=['-D', 'plot_html_show_source_link=0'])
+    assert "index-1.py" not in [p.name for p in html_dir2.iterdir()]
+
+
 def build_sphinx_html(source_dir, doctree_dir, html_dir, extra_args=None):
     # Build the pages with warnings turned into errors
     extra_args = [] if extra_args is None else extra_args
