Document standard backends in matplotlib.use()

timhoffm · timhoffm · commit bf9862c9dbe2 · 2018-09-25T19:51:34.000+02:00
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -1319,8 +1319,19 @@ def use(arg, warn=True, force=False):
     ----------
     arg : str
         The backend to switch to.  This can either be one of the
-        'standard' backend names or a string of the form
-        ``module://my.module.name``.  This value is case-insensitive.
+        'standard' backend names:
+
+        - interactive backends:
+          'GTK3Agg', 'GTK3Cairo', 'MacOSX', 'nbAgg',
+          'Qt4Agg', 'Qt4Cairo', 'Qt5Agg', 'Qt5Cairo',
+          'TkAgg', 'TkCairo', 'WebAgg', 'WX', 'WXAgg', 'WXCairo'
+
+        - non-interactive backends:
+          'agg', 'cairo', 'pdf', 'pgf', 'ps', 'svg', 'template'
+
+        or a string of the form: ``module://my.module.name``.
+
+        This value is case-insensitive.
 
     warn : bool, optional
         If True, warn if this is called after pyplot has been imported
@@ -1332,7 +1343,6 @@ def use(arg, warn=True, force=False):
         If True, attempt to switch the backend.  This defaults to
         False.
 
-
     """
     name = validate_backend(arg)
 
diff --git a/lib/matplotlib/tests/test_matplotlib.py b/lib/matplotlib/tests/test_matplotlib.py
@@ -0,0 +1,21 @@
+import matplotlib
+import matplotlib.rcsetup
+
+
+def test_use_doc_standard_backends():
+    """
+    Test that the standard backends mentioned in the docstring of
+    matplotlib.use() are the same as in matplotlib.rcsetup.
+    """
+    def parse(key):
+        backends = []
+        for line in matplotlib.use.__doc__.split(key)[1].split('\n'):
+            if not line or not line.strip().startswith("'"):
+                break
+            backends += [e.strip().strip("'") for e in line.split(',') if e]
+        return backends
+
+    assert (set(parse('- interactive backends:\n')) ==
+            set(matplotlib.rcsetup.interactive_bk))
+    assert (set(parse('- non-interactive backends:\n')) ==
+            set(matplotlib.rcsetup.non_interactive_bk))
