DOC: re-order the interactive backends in an opinionated way

tacaswell · tacaswell · commit 56a755244c6c · 2017-08-26T22:12:46.000-04:00
Also add IPython magic details
diff --git a/tutorials/introductory/usage.py b/tutorials/introductory/usage.py
@@ -399,10 +399,6 @@ def my_plotter(ax, data1, data2, param_dict):
 #                 :term:`pdf`
 #                 :term:`svg`
 #                 ...
-# :term:`GDK`     :term:`png`    :term:`raster graphics` --
-#                 :term:`jpg`    the `Gimp Drawing Kit`_ Deprecated in 2.0
-#                 :term:`tiff`
-#                 ...
 # =============   ============   ================================================
 #
 # And here are the user interfaces and renderer combinations supported;
@@ -413,27 +409,41 @@ def my_plotter(ax, data1, data2, param_dict):
 # ============   ================================================================
 # Backend        Description
 # ============   ================================================================
-# GTKAgg         Agg rendering to a :term:`GTK` 2.x canvas (requires PyGTK_ and
-#                pycairo_ or cairocffi_; Python2 only)
+# Qt5Agg         Agg rendering in a :term:`Qt5` canvas (requires PyQt5_).  This
+#                backend can be activated in IPython with ``%matplotlib qt5``.
+# ipympl         Agg rendering embedded in a Jupyter widget.  This can be enabled
+#                in a Jupyter notebook with ``%matplotlib ipympl``
 # GTK3Agg        Agg rendering to a :term:`GTK` 3.x canvas (requires PyGObject_
 #                and pycairo_ or cairocffi_)
-# GTK            GDK rendering to a :term:`GTK` 2.x canvas (not recommended and d
-#                eprecated in 2.0) (requires PyGTK_ and pycairo_ or cairocffi_;
-#                Python2 only)
-# GTKCairo       Cairo rendering to a :term:`GTK` 2.x canvas (requires PyGTK_
-#                and pycairo_ or cairocffi_; Python2 only)
+#                This backend can be activated in IPython with
+#                ``%matplotlib gtk3``.
+# macosx         Agg rendering into a Cocoa canvas in OSX.
+#                This backend can be activated in IPython with
+#                ``%matplotlib osx``.
+# TkAgg          Agg rendering to a :term:`Tk` canvas (requires TkInter_).
+#                This backend can be activated in IPython with
+#                ``%matplotlib tk``.
+# nbAgg          Embed an interactive figure in a Jupyter classic notebook.  This
+#                backend can be enabled in Jupyter notebooks via
+#                ``%matplotlib notebook``.
+# WebAgg         On ``show()`` will start a tornado server with an interactive
+#                figure.
 # GTK3Cairo      Cairo rendering to a :term:`GTK` 3.x canvas (requires PyGObject_
 #                and pycairo_ or cairocffi_)
+# Qt4Agg         Agg rendering to a :term:`Qt4` canvas (requires PyQt4_
+#                or ``pyside``).
+#                This backend can be activated in IPython with
+#                ``%matplotlib qt4``.
+# GTKAgg         Agg rendering to a :term:`GTK` 2.x canvas (requires PyGTK_ and
+#                pycairo_ or cairocffi_; Python2 only)
+#                This backend can be activated in IPython with
+#                ``%matplotlib gtk``.
+# GTKCairo       Cairo rendering to a :term:`GTK` 2.x canvas (requires PyGTK_
+#                and pycairo_ or cairocffi_; Python2 only)
 # WXAgg          Agg rendering to a :term:`wxWidgets` canvas
-#                (requires wxPython_)
-# WX             Native :term:`wxWidgets` drawing to a :term:`wxWidgets` Canvas
-#                (not recommended and deprecated in 2.0) (requires wxPython_)
-# TkAgg          Agg rendering to a :term:`Tk` canvas (requires TkInter_)
-# Qt4Agg         Agg rendering to a :term:`Qt4` canvas (requires PyQt4_ or ``pyside``)
-# Qt5Agg         Agg rendering in a :term:`Qt5` canvas (requires PyQt5_)
-# macosx         Cocoa rendering in OSX windows
-#                (presently lacks blocking show() behavior when matplotlib
-#                is in non-interactive mode)
+#                (requires wxPython_).
+#                This backend can be activated in IPython with
+#                ``%matplotlib wx``.
 # ============   ================================================================
 #
 # .. _`Anti-Grain Geometry`: http://antigrain.com/
