Add :code-caption: option to plot directive

Closes matplotlib#30740

Author: duncanmmacleod

lib/matplotlib/sphinxext/plot_directive.py

@@ -84,6 +84,11 @@
     figure. This overwrites the caption given in the content, when the plot
     is generated from a file.
 
+``:code-caption:`` : str
+    If specified, the option's argument will be used as a caption for the
+    code block (when ``:include-source:`` is used). This is added as the
+    ``:caption:`` option to the ``.. code-block::`` directive.
+
 Additionally, this directive supports all the options of the `image directive
 <https://docutils.sourceforge.io/docs/ref/rst/directives.html#image>`_,
 except for ``:target:`` (since plot will add its own target).  These include
@@ -281,6 +286,7 @@ class PlotDirective(Directive):
         'context': _option_context,
         'nofigs': directives.flag,
         'caption': directives.unchanged,
+        'code-caption': directives.unchanged,
         }
 
     def run(self):
@@ -952,8 +958,11 @@ def run(arguments, content, options, state_machine, state, lineno):
             if is_doctest:
                 lines = ['', *code_piece.splitlines()]
             else:
-                lines = ['.. code-block:: python', '',
-                         *textwrap.indent(code_piece, '    ').splitlines()]
+                lines = ['.. code-block:: python']
+                if 'code-caption' in options:
+                    code_caption = options['code-caption'].replace('\n', ' ')
+                    lines.append(f'   :caption: {code_caption}')
+                lines.extend(['', *textwrap.indent(code_piece, '    ').splitlines()])
             source_code = "\n".join(lines)
         else:
             source_code = ""

lib/matplotlib/tests/test_sphinxext.py

@@ -205,6 +205,30 @@ def test_plot_html_show_source_link_custom_basename(tmp_path):
     assert 'custom-name.py' in html_content
 
 
+def test_plot_html_code_caption(tmp_path):
+    # Test that :code-caption: option adds caption to code block
+    shutil.copyfile(tinypages / 'conf.py', tmp_path / 'conf.py')
+    shutil.copytree(tinypages / '_static', tmp_path / '_static')
+    doctree_dir = tmp_path / 'doctrees'
+    (tmp_path / 'index.rst').write_text("""
+.. plot::
+    :include-source:
+    :code-caption: Example plotting code
+
+    import matplotlib.pyplot as plt
+    plt.plot([1, 2, 3], [1, 4, 9])
+""")
+    html_dir = tmp_path / '_build' / 'html'
+    build_sphinx_html(tmp_path, doctree_dir, html_dir)
+
+    # Check that the HTML contains the code caption
+    html_content = (html_dir / 'index.html').read_text(encoding='utf-8')
+    assert 'Example plotting code' in html_content
+    # Verify the caption is associated with the code block
+    # (appears in a caption element)
+    assert '<p class="caption"' in html_content or 'caption' in html_content.lower()
+
+
 def test_srcset_version(tmp_path):
     shutil.copytree(tinypages, tmp_path, dirs_exist_ok=True,
                     ignore=shutil.ignore_patterns('_build', 'doctrees',