From c54ba70e46c43e056a2de6b589ed26142eb2d13d Mon Sep 17 00:00:00 2001
From: Antony Lee <anntzer.lee@gmail.com>
Date: Thu, 4 Oct 2018 14:38:35 +0200
Subject: [PATCH] Backport PR #12257: Document standard backends in
 matplotlib.use()

---
 lib/matplotlib/__init__.py              | 32 ++++++++++++++++++-------
 lib/matplotlib/tests/test_matplotlib.py | 21 ++++++++++++++++
 tutorials/introductory/usage.py         |  3 +++
 3 files changed, 48 insertions(+), 8 deletions(-)
 create mode 100644 lib/matplotlib/tests/test_matplotlib.py

diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
index f7b37ee3b612..e265ddff0542 100644
--- 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
new file mode 100644
index 000000000000..3981e8009993
--- /dev/null
+++ 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
index 67fae806c8a9..2e6a05bd101c 100644
--- 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
 # ========
 #