Merge pull request #24000 from timhoffm/pyplot-test

timhoffm · web-flow · commit f4f9528ebd88 · 2022-10-16T12:38:36.000+02:00
Generalize validation that pyplot commands are documented
diff --git a/doc/api/next_api_changes/deprecations/24000-TH.rst b/doc/api/next_api_changes/deprecations/24000-TH.rst
@@ -0,0 +1,5 @@
+``matplotlib.pyplot.get_plot_commands``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+... is a pending deprecation. This is considered internal and no end-user
+should need it.
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -2028,20 +2028,23 @@ def thetagrids(angles=None, labels=None, fmt=None, **kwargs):
     return lines, labels
 
 
-_NON_PLOT_COMMANDS = {
-    'connect', 'disconnect', 'get_current_fig_manager', 'ginput',
-    'new_figure_manager', 'waitforbuttonpress'}
-
-
+@_api.deprecated("3.7", pending=True)
 def get_plot_commands():
     """
     Get a sorted list of all of the plotting commands.
     """
+    NON_PLOT_COMMANDS = {
+        'connect', 'disconnect', 'get_current_fig_manager', 'ginput',
+        'new_figure_manager', 'waitforbuttonpress'}
+    return (name for name in _get_pyplot_commands()
+            if name not in NON_PLOT_COMMANDS)
+
+
+def _get_pyplot_commands():
     # This works by searching for all functions in this module and removing
     # a few hard-coded exclusions, as well as all of the colormap-setting
     # functions, and anything marked as private with a preceding underscore.
-    exclude = {'colormaps', 'colors', 'get_plot_commands',
-               *_NON_PLOT_COMMANDS, *colormaps}
+    exclude = {'colormaps', 'colors', 'get_plot_commands', *colormaps}
     this_module = inspect.getmodule(get_plot_commands)
     return sorted(
         name for name, obj in globals().items()
diff --git a/lib/matplotlib/tests/test_pyplot.py b/lib/matplotlib/tests/test_pyplot.py
@@ -1,5 +1,4 @@
 import difflib
-import re
 
 import numpy as np
 import subprocess
@@ -367,10 +366,42 @@ def test_doc_pyplot_summary():
     if not pyplot_docs.exists():
         pytest.skip("Documentation sources not available")
 
-    lines = pyplot_docs.read_text()
-    m = re.search(r':nosignatures:\n\n(.*?)\n\n', lines, re.DOTALL)
-    doc_functions = set(line.strip() for line in m.group(1).split('\n'))
-    plot_commands = set(plt.get_plot_commands())
+    def extract_documented_functions(lines):
+        """
+        Return a list of all the functions that are mentioned in the
+        autosummary blocks contained in *lines*.
+
+        An autosummary block looks like this::
+
+            .. autosummary::
+               :toctree: _as_gen
+               :template: autosummary.rst
+               :nosignatures:
+
+               plot
+               plot_date
+
+        """
+        functions = []
+        in_autosummary = False
+        for line in lines:
+            if not in_autosummary:
+                if line.startswith(".. autosummary::"):
+                    in_autosummary = True
+            else:
+                if not line or line.startswith("   :"):
+                    # empty line or autosummary parameter
+                    continue
+                if not line[0].isspace():
+                    # no more indentation: end of autosummary block
+                    in_autosummary = False
+                    continue
+                functions.append(line.strip())
+        return functions
+
+    lines = pyplot_docs.read_text().split("\n")
+    doc_functions = set(extract_documented_functions(lines))
+    plot_commands = set(plt._get_pyplot_commands())
     missing = plot_commands.difference(doc_functions)
     if missing:
         raise AssertionError(
