Generalize validation that pyplot commands are documented

timhoffm · timhoffm · commit 2c0f9609aa17 · 2022-09-25T00:34:02.000+02:00
Until now, the test made some exclusions (_NON_PLOT_COMMANDS) and
reqired all functions to be documented in a single autosummary block.

This change ensures the documentation of the _NON_PLOT_COMMANDS
and it allows the commands to be spread across arbitrary many
autosummary sections. This is in preparation of regrouping the pyplot
commands similar to the Axes documentation.

This also pending deprecates `pyplot.get_plot_commands`, which should
not be a public function. I'm defensive by using pending, because if
`get_plot_commands` is used somewhere, that's most likely some
downstream lib and we want to give them time to adapt.
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -2017,20 +2017,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
@@ -367,10 +367,41 @@ 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 functions that are mentioned in autosummary
+        blocks contain 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():
+                    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(
