plot directive: caption-option

Ulrich J. Herter · Ulrich J. Herter · commit 90069b47c44a · 2020-09-07T12:13:53.000+02:00
This new option allows the user to add a caption to plots with the
plotting code given in the directive's contents.

* The option :caption: enforces a caption.

* The option take precedence over the contents.

* Tested and documented in the modul's doc string.

* Note in next_whats_new
diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py
@@ -71,6 +71,11 @@
         If specified, the code block will be run, but no figures will be
         inserted.  This is usually useful with the ``:context:`` option.
 
+    caption : str
+        If specified, the option's argument will be used as a caption for the
+        figure. This overwrites the caption given in the content, when the plot
+        is generated from a file.
+
 Additionally, this directive supports all of the options of the `image`
 directive, except for *target* (since plot will add its own target).  These
 include *alt*, *height*, *width*, *scale*, *align* and *class*.
@@ -240,6 +245,7 @@ class PlotDirective(Directive):
         'context': _option_context,
         'nofigs': directives.flag,
         'encoding': directives.encoding,
+        'caption': directives.unchanged,
         }
 
     def run(self):
@@ -633,8 +639,9 @@ def run(arguments, content, options, state_machine, state, lineno):
             source_file_name = os.path.join(setup.confdir, config.plot_basedir,
                                             directives.uri(arguments[0]))
 
-        # If there is content, it will be passed as a caption.
-        caption = '\n'.join(content)
+        # If there is content, it will be passed as a caption, if the caption
+        # option is not present.
+        caption = options.get("caption", '\n'.join(content))
 
         # If the optional function name is provided, use it
         if len(arguments) == 2:
@@ -652,7 +659,7 @@ def run(arguments, content, options, state_machine, state, lineno):
         base, ext = os.path.splitext(os.path.basename(source_file_name))
         output_base = '%s-%d.py' % (base, counter)
         function_name = None
-        caption = ''
+        caption = options.get('caption', '')
 
     base, source_ext = os.path.splitext(output_base)
     if source_ext in ('.py', '.rst', '.txt'):
diff --git a/lib/matplotlib/tests/test_sphinxext.py b/lib/matplotlib/tests/test_sphinxext.py
@@ -21,6 +21,7 @@ def test_tinypages(tmpdir):
            str(Path(__file__).parent / 'tinypages'), str(html_dir)]
     proc = Popen(cmd, stdout=PIPE, stderr=PIPE, universal_newlines=True)
     out, err = proc.communicate()
+
     assert proc.returncode == 0, \
         "sphinx build failed with stdout:\n{}\nstderr:\n{}\n".format(out, err)
     if err:
@@ -52,3 +53,7 @@ def plot_file(num):
     assert filecmp.cmp(range_6, html_dir / 'range6.png')
     # check if figure caption made it into html file
     assert b'This is the caption for plot 15.' in html_contents
+    # check if figure caption usin :caption: made it into html file
+    assert b'Plot 17 uses the caption option.' in html_contents
+    # check if figure caption made it into html file
+    assert b'This is the actual caption for plot 18.' in html_contents
diff --git a/lib/matplotlib/tests/tinypages/some_plots.rst b/lib/matplotlib/tests/tinypages/some_plots.rst
@@ -127,3 +127,19 @@ Plot 16 uses a specific function in a file with plot commands:
 .. plot:: range6.py range6
 
 
+Plot 17 gets a caption specified by the :caption: option:
+
+.. plot::
+   :caption: Plot 17 uses the caption option.
+
+   plt.figure()
+   plt.plot(range(6))
+
+
+Plot 18 uses an external file with the plot commands and a caption
+the using :caption: option:
+
+.. plot:: range4.py
+   :caption: This is the actual caption for plot 18.
+
+   This is the caption for plot 18.
