Update backends docs.

matplotlib · anntzer · Jun 15, 2017 · Jun 18, 2017 · Jun 18, 2017 · Jun 18, 2017
commit d2f2bc0c61b18a2ad79d1060c5e5cf51d74bc2aa
diff --git a/doc/users/whats_new/qtcairo.rst b/doc/users/whats_new/qtcairo.rst
@@ -0,0 +1,5 @@
+Cairo rendering for Qt canvases
+-------------------------------
+
+The new ``Qt4Cairo`` and ``Qt5Cairo`` backends allow Qt canvases to use Cairo
+rendering instead of Agg.
diff --git a/tutorials/introductory/usage.py b/tutorials/introductory/usage.py
@@ -322,13 +322,18 @@ def my_plotter(ax, data1, data2, param_dict):
 #        backend : WXAgg   # use wxpython with antigrain (agg) rendering
 #
 # #. Setting the :envvar:`MPLBACKEND` environment
-#    variable, either for your current shell or for a single script::
+#    variable, either for your current shell or for a single script.  On Unix::
 #
-#         > export MPLBACKEND="module://my_backend"
+#         > export MPLBACKEND=module://my_backend
 #         > python simple_plot.py
 #
 #         > MPLBACKEND="module://my_backend" python simple_plot.py
 #
+#    On Windows, only the former is possible::
+#
+#         > set MPLBACKEND=module://my_backend
+#         > python simple_plot.py
+#
 #    Setting this environment variable will override the ``backend`` parameter
 #    in *any* ``matplotlibrc``, even if there is a ``matplotlibrc`` in your
 #    current working directory. Therefore setting :envvar:`MPLBACKEND`
@@ -360,19 +365,18 @@ def my_plotter(ax, data1, data2, param_dict):
 # methods given above.
 #
 # If, however, you want to write graphical user interfaces, or a web
-# application server (:ref:`howto-webapp`), or need a better
-# understanding of what is going on, read on. To make things a little
-# more customizable for graphical user interfaces, matplotlib separates
-# the concept of the renderer (the thing that actually does the drawing)
-# from the canvas (the place where the drawing goes).  The canonical
-# renderer for user interfaces is ``Agg`` which uses the `Anti-Grain
-# Geometry`_ C++ library to make a raster (pixel) image of the figure.
-# All of the user interfaces except ``macosx`` can be used with
-# agg rendering, e.g.,
-# ``WXAgg``, ``GTKAgg``, ``QT4Agg``, ``QT5Agg``, ``TkAgg``.  In
-# addition, some of the user interfaces support other rendering engines.
-# For example, with GTK, you can also select GDK rendering (backend
-# ``GTK`` deprecated in 2.0) or Cairo rendering (backend ``GTKCairo``).
+# application server (:ref:`howto-webapp`), or need a better understanding of
+# what is going on, read on.  To make things a little more customizable for
+# graphical user interfaces, matplotlib separates the concept of the renderer
+# (the thing that actually does the drawing) from the canvas (the place where
+# the drawing goes).  The canonical renderer for user interfaces is ``Agg``
+# which uses the `Anti-Grain Geometry`_ C++ library to make a raster (pixel)
+# image of the figure.  All of the user interfaces except ``macosx`` can
+# be used with Agg rendering, e.g., ``GTKAgg``, ``GTK3Agg``, ``Qt4Agg``,
+# ``Qt5Agg``, ``TkAgg``, ``WxAgg``.  In addition, some of the user interfaces
+# support other rendering engines.  For example, with GTK, GTK3, and QT5,
+# you can also select Cairo rendering (backends ``GTKCairo``, ``GTK3Cairo``,
+# ``Qt5Cairo``).
 #
 # For the rendering engines, one can also distinguish between `vector
 # <https://en.wikipedia.org/wiki/Vector_graphics>`_ or `raster
@@ -397,65 +401,61 @@ def my_plotter(ax, data1, data2, param_dict):
 #                                `Portable Document Format`_
 # SVG             :term:`svg`    :term:`vector graphics` --
 #                                `Scalable Vector Graphics`_
-# :term:`Cairo`   :term:`png`    :term:`vector graphics` --
-#                 :term:`ps`     `Cairo graphics`_
-#                 :term:`pdf`
+# :term:`Cairo`   :term:`png`    :term:`raster graphics` and
+#                 :term:`ps`     :term:`vector graphics` -- using the
+#                 :term:`pdf`    `Cairo graphics`_ library
 #                 :term:`svg`
-#                 ...
 # =============   ============   ================================================
 #
 # And here are the user interfaces and renderer combinations supported;
 # these are *interactive backends*, capable of displaying to the screen
 # and of using appropriate renderers from the table above to write to
 # a file:
 #
-# ============   ================================================================
-# Backend        Description
-# ============   ================================================================
-# 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.  (requires ipympl)
-#                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_)
-#                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_.  v4.0 (in beta) is
-#                required for python3).
-#                This backend can be activated in IPython with
-#                ``%matplotlib wx``.
-# ============   ================================================================
+# ========= ================================================================
+# Backend   Description
+# ========= ================================================================
+# 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.  (requires ipympl).
+#           This backend 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_).  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.
+# Qt5Cairo  Cairo rendering in a :term:`Qt5` canvas (requires PyQt5_ and
+#           cairocffi_).
+# 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``.
+# Qt4Cairo  Cairo rendering in a :term:`Qt5` canvas (requires PyQt5_ and
+#           cairocffi_).
+# 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_;
+#           v4.0 (in beta) is required for Python3). This backend can be
+#           activated in IPython with ``%matplotlib wx``.
+# ========= ================================================================
 #
 # .. _`Anti-Grain Geometry`: http://antigrain.com/
 # .. _Postscript: https://en.wikipedia.org/wiki/PostScript
 # .. _`Portable Document Format`: https://en.wikipedia.org/wiki/Portable_Document_Format
 # .. _`Scalable Vector Graphics`: https://en.wikipedia.org/wiki/Scalable_Vector_Graphics
-# .. _`Cairo graphics`: https://en.wikipedia.org/wiki/Cairo_(graphics)
+# .. _`Cairo graphics`: https://wwW.cairographics.org
 # .. _`Gimp Drawing Kit`: https://en.wikipedia.org/wiki/GDK
 # .. _PyGTK: http://www.pygtk.org
 # .. _PyGObject: https://wiki.gnome.org/action/show/Projects/PyGObject
@@ -489,11 +489,8 @@ def my_plotter(ax, data1, data2, param_dict):
 # GTK and Cairo
 # -------------
 #
-# Both `GTK2` and `GTK3` have implicit dependencies on PyCairo regardless of the
-# specific Matplotlib backend used. Unfortunatly the latest release of PyCairo
-# for Python3 does not implement the Python wrappers needed for the `GTK3Agg`
-# backend. `Cairocffi` can be used as a replacement which implements the correct
-# wrapper.
+# Both `GTK2` and `GTK3` depend on a Cairo wrapper (PyCairo or cairocffi) even
+# if the Agg renderer is used.  On Python3, only cairocffi is supported.
 #
 # How do I select PyQt4 or PySide?
 # --------------------------------