add :filter-warning: option to plot directive

story645 · story645 · commit dc2366a70cf8 · 2023-10-04T19:10:37.000-04:00
diff --git a/doc/users/prev_whats_new/whats_new_3.6.0.rst b/doc/users/prev_whats_new/whats_new_3.6.0.rst
@@ -553,6 +553,7 @@ them in order to locate a required glyph.
    :caption: Demonstration of mixed English and Chinese text with font fallback.
    :alt: The phrase "There are 几个汉字 in between!" rendered in various fonts.
    :include-source: True
+   :filter-warning: Glyph
 
    plt.rcParams["font.size"] = 20
    fig = plt.figure(figsize=(4.75, 1.85))
diff --git a/galleries/users_explain/text/fonts.py b/galleries/users_explain/text/fonts.py
@@ -180,8 +180,10 @@
 
 .. plot::
    :include-source:
+   :filter-warning: Glyph
    :caption: The string "There are 几个汉字 in between!" rendered with 2 fonts.
 
+
    fig, ax = plt.subplots()
    ax.text(
        .5, .5, "There are 几个汉字 in between!",
diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py
@@ -78,6 +78,12 @@
     figure. This overwrites the caption given in the content, when the plot
     is generated from a file.
 
+``:filter-warning:`` : str
+    When specified, will ignore warnings that match the input string, which is
+    a warnings filter `message regex <msg>`_ string.
+
+.. _msg: https://docs.python.org/3/library/warnings.html#the-warnings-filter
+
 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
@@ -177,6 +183,7 @@
 import sys
 import textwrap
 import traceback
+import warnings
 
 from docutils.parsers.rst import directives, Directive
 from docutils.parsers.rst.directives.images import Image
@@ -221,6 +228,10 @@ def _option_format(arg):
     return directives.choice(arg, ('python', 'doctest'))
 
 
+def _option_string(arg):
+    return arg if arg.strip() else False
+
+
 def mark_plot_labels(app, document):
     """
     To make plots referenceable, we need to move the reference from the
@@ -271,7 +282,8 @@ class PlotDirective(Directive):
         'context': _option_context,
         'nofigs': directives.flag,
         'caption': directives.unchanged,
-        }
+        'filter-warning': _option_string,
+    }
 
     def run(self):
         """Run the plot directive."""
@@ -854,16 +866,20 @@ 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)
+        with warnings.catch_warnings(record=True) as w:
+            if msg := options.get('filter-warning', False):
+                warnings.filterwarnings('ignore', message=msg)
+
+            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
