DOC: reinstate "codex" search term

rcomer · rcomer · commit c9f728992464 · 2025-12-14T19:45:23.000Z
Our monkeypatching of sphinx-gallery's EXAMPLE_HEADER in conf.py no longer works when using the parallel build option. One way around this is to monkey-patch for each individual example by adding a function that does it in the "reset_modules" config option. Closes #29542
diff --git a/doc/conf.py b/doc/conf.py
@@ -208,8 +208,6 @@ def _check_dependencies():
 else:
     sg_matplotlib_animations = True
 
-# The following import is only necessary to monkey patch the signature later on
-from sphinx_gallery import gen_rst
 
 # Prevent plt.show() from emitting a non-GUI backend warning.
 warnings.filterwarnings('ignore', category=UserWarning,
@@ -307,7 +305,7 @@ def autodoc_process_bases(app, name, obj, options, bases):
     'reference_url': {'matplotlib': None, 'mpl_toolkits': None},
     'prefer_full_module': {r'mpl_toolkits\.'},
     'remove_config_comments': True,
-    'reset_modules': ('matplotlib', clear_basic_units),
+    'reset_modules': ('matplotlib', clear_basic_units, 'sphinxext.util.patch_header'),
     'subsection_order': gallery_order_sectionorder,
     'thumbnail_size': (320, 224),
     'within_subsection_order': gallery_order_subsectionorder,
@@ -355,31 +353,6 @@ def gallery_image_warning_filter(record):
 mathmpl_fontsize = 11.0
 mathmpl_srcset = ['2x']
 
-# Monkey-patching gallery header to include search keywords
-gen_rst.EXAMPLE_HEADER = """
-.. DO NOT EDIT.
-.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
-.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
-.. "{0}"
-.. LINE NUMBERS ARE GIVEN BELOW.
-
-.. only:: html
-
-    .. meta::
-        :keywords: codex
-
-    .. note::
-        :class: sphx-glr-download-link-note
-
-        :ref:`Go to the end <sphx_glr_download_{1}>`
-        to download the full example code{2}
-
-.. rst-class:: sphx-glr-example-title
-
-.. _sphx_glr_{1}:
-
-"""
-
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
diff --git a/doc/sphinxext/util.py b/doc/sphinxext/util.py
@@ -1,5 +1,7 @@
 import sys
 
+from sphinx_gallery import gen_rst
+
 
 def matplotlib_reduced_latex_scraper(block, block_vars, gallery_conf,
                                      **kwargs):
@@ -19,3 +21,33 @@ def matplotlib_reduced_latex_scraper(block, block_vars, gallery_conf,
 # Clear basic_units module to re-register with unit registry on import.
 def clear_basic_units(gallery_conf, fname):
     return sys.modules.pop('basic_units', None)
+
+
+# Monkey-patching gallery header to include search keywords
+EXAMPLE_HEADER = """
+.. DO NOT EDIT.
+.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
+.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
+.. "{0}"
+.. LINE NUMBERS ARE GIVEN BELOW.
+
+.. only:: html
+
+    .. meta::
+        :keywords: codex
+
+    .. note::
+        :class: sphx-glr-download-link-note
+
+        :ref:`Go to the end <sphx_glr_download_{1}>`
+        to download the full example code{2}
+
+.. rst-class:: sphx-glr-example-title
+
+.. _sphx_glr_{1}:
+
+"""
+
+
+def patch_header(gallery_conf, fname):
+    gen_rst.EXAMPLE_HEADER = EXAMPLE_HEADER
diff --git a/lib/matplotlib/tests/test_doc.py b/lib/matplotlib/tests/test_doc.py
@@ -7,7 +7,7 @@ def test_sphinx_gallery_example_header():
     This test monitors that the version we have copied is still the same as
     the EXAMPLE_HEADER in sphinx-gallery. If sphinx-gallery changes its
     EXAMPLE_HEADER, this test will start to fail. In that case, please update
-    the monkey-patching of EXAMPLE_HEADER in conf.py.
+    the monkey-patching of EXAMPLE_HEADER in sphinxext/util.py.
     """
     pytest.importorskip('sphinx_gallery', minversion='0.20.0')
     from sphinx_gallery import gen_rst
