From 23f61e8346d295492d2ec8fcb40b6415c4903f4e Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Fri, 14 Jun 2019 01:27:28 +0200 Subject: [PATCH] Improve backends documentation --- tutorials/introductory/usage.py | 98 +++++++++++++++++++++------------ 1 file changed, 62 insertions(+), 36 deletions(-) diff --git a/tutorials/introductory/usage.py b/tutorials/introductory/usage.py index 4dc40c839afa..55983540ae32 100644 --- a/tutorials/introductory/usage.py +++ b/tutorials/introductory/usage.py @@ -186,7 +186,7 @@ # # Matplotlib's documentation and examples use both the OO and the pyplot # approaches (which are equally powerful), and you should feel free to use -# either (however, it is preferrable pick one of them and stick to it, instead +# either (however, it is preferable pick one of them and stick to it, instead # of mixing them). In general, we suggest to restrict pyplot to interactive # plotting (e.g., in a Jupyter notebook), and to prefer the OO-style for # non-interactive plotting (in functions and scripts that are intended to be @@ -289,44 +289,60 @@ def my_plotter(ax, data1, data2, param_dict): # "interactive backends") and hardcopy backends to make image files # (PNG, SVG, PDF, PS; also referred to as "non-interactive backends"). # -# There are three ways to configure your backend. If they conflict each other, -# the method mentioned last in the following list will be used, e.g. calling -# :func:`~matplotlib.use()` will override the setting in your ``matplotlibrc``. +# Selecting a backend +# ------------------- # -# #. The :rc:`backend` parameter in your ``matplotlibrc`` file (see -# :doc:`/tutorials/introductory/customizing`):: +# There are three ways to configure your backend: +# +# 1. The :rc:`backend` parameter in your ``matplotlibrc`` file +# 2. The :envvar:`MPLBACKEND` environment variable +# 3. The function :func:`matplotlib.use` +# +# A more detailed description is given below. +# +# If multiple of these are configurations are present, the last one from the +# list takes precedence; e.g. calling :func:`matplotlib.use()` will override +# the setting in your ``matplotlibrc``. +# +# If no backend is explicitly set, Matplotlib automatically detects a usable +# backend based on what is available on your system and on whether a GUI event +# loop is already running. On Linux, if the environment variable +# :envvar:`DISPLAY` is unset, the "event loop" is identified as "headless", +# which causes a fallback to a noninteractive backend (agg). +# +# Here is a detailed description of the configuration methods: +# +# #. Setting :rc:`backend` in your ``matplotlibrc`` file:: # # backend : qt5agg # use pyqt5 with antigrain (agg) rendering # -# If no backend is explicitly set in the ``matplotlibrc`` file, Matplotlib -# automatically detects a usable backend based on what is available on your -# system and on whether a GUI event loop is already running. +# See also :doc:`/tutorials/introductory/customizing`. +# +# #. Setting the :envvar:`MPLBACKEND` environment variable: # -# On Linux, if the environment variable :envvar:`DISPLAY` is unset, the -# "event loop" is identified as "headless", which causes a fallback to a -# noninteractive backend (agg). +# You can set the environment variable either for your current shell or for +# a single script. # -# #. Setting the :envvar:`MPLBACKEND` environment variable, either for your -# current shell or for a single script. On Unix:: +# On Unix:: # -# > export MPLBACKEND=module://my_backend +# > export MPLBACKEND=qt5agg # > python simple_plot.py # -# > MPLBACKEND="module://my_backend" python simple_plot.py +# > MPLBACKEND=qt5agg python simple_plot.py # # On Windows, only the former is possible:: # -# > set MPLBACKEND=module://my_backend +# > set MPLBACKEND=qt5agg # > 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` +# current working directory. Therefore, setting :envvar:`MPLBACKEND` # globally, e.g. in your ``.bashrc`` or ``.profile``, is discouraged as it # might lead to counter-intuitive behavior. # -# #. If your script depends on a specific backend you can use the -# :func:`~matplotlib.use` function:: +# #. If your script depends on a specific backend you can use the function +# :func:`matplotlib.use`:: # # import matplotlib # matplotlib.use('PS') # generate postscript output by default @@ -339,9 +355,9 @@ def my_plotter(ax, data1, data2, param_dict): # use a different backend. Therefore, you should avoid explicitly calling # `~matplotlib.use` unless absolutely necessary. # -# .. note:: -# Backend name specifications are not case-sensitive; e.g., 'GTK3Agg' -# and 'gtk3agg' are equivalent. +# +# The builtin backends +# -------------------- # # With a typical installation of matplotlib, such as from a # binary installer or a linux distribution package, a good default @@ -426,6 +442,10 @@ def my_plotter(ax, data1, data2, param_dict): # This backend can be activated in IPython with ``%matplotlib wx``. # ========= ================================================================ # +# .. note:: +# The names of builtin backends case-insensitive; e.g., 'Qt5Agg' and +# 'qt5agg' are equivalent. +# # .. _`Anti-Grain Geometry`: http://antigrain.com/ # .. _Postscript: https://en.wikipedia.org/wiki/PostScript # .. _`Portable Document Format`: https://en.wikipedia.org/wiki/Portable_Document_Format @@ -440,7 +460,7 @@ def my_plotter(ax, data1, data2, param_dict): # .. _PyQt5: https://riverbankcomputing.com/software/pyqt/intro # # ipympl -# ------ +# ^^^^^^ # # The Jupyter widget ecosystem is moving too fast to support directly in # Matplotlib. To install ipympl @@ -460,13 +480,13 @@ def my_plotter(ax, data1, data2, param_dict): # for more details. # # GTK and Cairo -# ------------- +# ^^^^^^^^^^^^^ # # `GTK3` backends (*both* `GTK3Agg` and `GTK3Cairo`) depend on Cairo # (pycairo>=1.11.0 or cairocffi). # # How do I select PyQt4 or PySide? -# -------------------------------- +# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ # # The `QT_API` environment variable can be set to either `pyqt` or `pyside` # to use `PyQt4` or `PySide`, respectively. @@ -475,10 +495,18 @@ def my_plotter(ax, data1, data2, param_dict): # :mod:`matplotlib` first tries to import it, if the import fails, it tries to # import `PySide`. # +# Using non-builtin backends +# -------------------------- +# More generally, any importable backend can be selected by using any of the +# methods above. If `name.of.the.backend` is the module containing the backend, +# use `module://name.of.the.backend` as the backend name, e.g. +# `matplotlib.use('module://name.of.the.backend')`. +# +# # .. _interactive-mode: # # What is interactive mode? -# =================================== +# ========================= # # Use of an interactive backend (see :ref:`what-is-a-backend`) # permits--but does not by itself require or ensure--plotting @@ -511,7 +539,8 @@ def my_plotter(ax, data1, data2, param_dict): # Interactive mode works with suitable backends in ipython and in # the ordinary python shell, but it does *not* work in the IDLE IDE. # If the default backend does not support interactivity, an interactive -# backend can be explicitly activated using any of the methods discussed in `What is a backend?`_. +# backend can be explicitly activated using any of the methods discussed +# in `What is a backend?`_. # # # Interactive example @@ -524,18 +553,15 @@ def my_plotter(ax, data1, data2, param_dict): # plt.ion() # plt.plot([1.6, 2.7]) # -# Assuming you are running version 1.0.1 or higher, and you have -# an interactive backend installed and selected by default, you should -# see a plot, and your terminal prompt should also be active; you -# can type additional commands such as:: +# This will pop up a plot window. Your terminal prompt will remain active, so +# that you can type additional commands such as:: # # plt.title("interactive test") # plt.xlabel("index") # -# and you will see the plot being updated after each line. Since version 1.5, -# modifying the plot by other means *should* also automatically -# update the display on most backends. Get a reference to the :class:`~matplotlib.axes.Axes` instance, -# and call a method of that instance:: +# On most interactive backends, the figure window will also be updated if you +# change it via the object-oriented interface. E.g. get a reference to the +# `~matplotlib.axes.Axes` instance, and call a method of that instance:: # # ax = plt.gca() # ax.plot([3.1, 2.2])