Backport PR #12257: Document standard backends in matplotlib.use() (#12400)

meeseeksmachine · timhoffm · commit e6e6bda7cc53 · 2018-10-04T17:26:43.000+02:00
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -1323,16 +1323,23 @@ def use(arg, warn=True, force=False):
     """
     Set the matplotlib backend to one of the known backends.
 
-    To find out which backend is currently set, see
-    :func:`matplotlib.get_backend`.
-
-
     Parameters
     ----------
     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``.
+
+        Note: Standard backend names are case-insensitive here.
 
     warn : bool, optional
         If True, warn if this is called after pyplot has been imported
@@ -1344,7 +1351,10 @@ def use(arg, warn=True, force=False):
         If True, attempt to switch the backend.  This defaults to
         False.
 
-
+    See Also
+    --------
+    :ref:`backends`
+    matplotlib.get_backend
     """
     name = validate_backend(arg)
 
@@ -1383,7 +1393,13 @@ def use(arg, warn=True, force=False):
 
 
 def get_backend():
-    """Return the name of the current backend."""
+    """
+    Return the name of the current backend.
+
+    See Also
+    --------
+    matplotlib.use
+    """
     return rcParams['backend']
 
 
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.strip():
+                break
+            backends += [e.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))
diff --git a/tutorials/introductory/usage.py b/tutorials/introductory/usage.py
@@ -284,6 +284,9 @@ def my_plotter(ax, data1, data2, param_dict):
 # Again, for these simple examples this style seems like overkill, however
 # once the graphs get slightly more complex it pays off.
 #
+#
+# .. _backends:
+#
 # Backends
 # ========
 #

Original file line number	Diff line number	Diff line change
`@@ -284,6 +284,9 @@ def my_plotter(ax, data1, data2, param_dict):`
`284`	`284`	`# Again, for these simple examples this style seems like overkill, however`
`285`	`285`	`# once the graphs get slightly more complex it pays off.`
`286`	`286`	`#`
	`287`	`+#`
	`288`	`+# .. _backends:`
	`289`	`+#`
`287`	`290`	`# Backends`
`288`	`291`	`# ========`
`289`	`292`	`#`