Merge pull request matplotlib#24423 from anntzer/qtb

Tighten the Qt binding selection docs.

Author: timhoffm

doc/api/backend_gtk3_api.rst

@@ -1,8 +1,8 @@
 :mod:`.backend_gtk3agg`, :mod:`.backend_gtk3cairo`
 ==================================================
 
-**NOTE** These backends are not documented here, to avoid adding a dependency
-to building the docs.
+**NOTE** These :ref:`backends` are not documented here, to avoid adding a
+dependency to building the docs.
 
 .. redirect-from:: /api/backend_gtk3agg_api
 .. redirect-from:: /api/backend_gtk3cairo_api

doc/api/backend_gtk4_api.rst

@@ -1,8 +1,8 @@
 :mod:`.backend_gtk4agg`, :mod:`.backend_gtk4cairo`
 ==================================================
 
-**NOTE** These backends are not documented here, to avoid adding a dependency
-to building the docs.
+**NOTE** These :ref:`backends` are not documented here, to avoid adding a
+dependency to building the docs.
 
 .. redirect-from:: /api/backend_gtk4agg_api
 .. redirect-from:: /api/backend_gtk4cairo_api

doc/api/backend_qt_api.rst

@@ -1,8 +1,8 @@
 :mod:`.backend_qtagg`, :mod:`.backend_qtcairo`
 ==============================================
 
-**NOTE** These backends are not (auto) documented here, to avoid adding a
-dependency to building the docs.
+**NOTE** These :ref:`backends` are not (auto) documented here, to avoid adding
+a dependency to building the docs.
 
 .. redirect-from:: /api/backend_qt4agg_api
 .. redirect-from:: /api/backend_qt4cairo_api
@@ -26,39 +26,39 @@ supported Python bindings per version -- `PyQt5
 <https://www.riverbankcomputing.com/static/Docs/PyQt5/>`_ and `PySide2
 <https://doc.qt.io/qtforpython-5/contents.html>`_ for Qt5 and `PyQt6
 <https://www.riverbankcomputing.com/static/Docs/PyQt6/>`_ and `PySide6
-<https://doc.qt.io/qtforpython/contents.html>`_ for Qt6 [#]_.  While both PyQt
+<https://doc.qt.io/qtforpython/contents.html>`_ for Qt6 [#]_.  Matplotlib's
+qtagg and qtcairo backends (``matplotlib.backends.backend_qtagg`` and
+``matplotlib.backend.backend_qtcairo``) support all these bindings, with common
+parts factored out in the ``matplotlib.backends.backend_qt`` module.
+
+At runtime, these backends select the actual binding used as follows:
+
+1. If a binding's ``QtCore`` subpackage is already imported, that binding is
+   selected (the order for the check is ``PyQt6``, ``PySide6``, ``PyQt5``,
+   ``PySide2``).
+2. If the :envvar:`QT_API` environment variable is set to one of "PyQt6",
+   "PySide6", "PyQt5", "PySide2" (case-insensitive), that binding is selected.
+   (See also the documentation on :ref:`environment-variables`.)
+3. Otherwise, the first available backend in the order ``PyQt6``, ``PySide6``,
+   ``PyQt5``, ``PySide2`` is selected.
+
+In the past, Matplotlib used to have separate backends for each version of Qt
+(e.g. qt4agg/``matplotlib.backends.backend_qt4agg`` and
+qt5agg/``matplotlib.backends.backend_qt5agg``).  This scheme was dropped when
+support for Qt6 was added.  For back-compatibility, qt5agg/``backend_qt5agg``
+and qt5cairo/``backend_qt5cairo`` remain available; selecting one of these
+backends forces the use of a Qt5 binding.  Their use is discouraged and
+``backend_qtagg`` or ``backend_qtcairo`` should be preferred instead.  However,
+these modules will not be deprecated until we drop support for Qt5.
+
+While both PyQt
 and Qt for Python (aka PySide) closely mirror the underlying C++ API they are
 wrapping, they are not drop-in replacements for each other [#]_.  To account
 for this, Matplotlib has an internal API compatibility layer in
 `matplotlib.backends.qt_compat` which covers our needs.  Despite being a public
 module, we do not consider this to be a stable user-facing API and it may
 change without warning [#]_.
 
-Previously Matplotlib's Qt backends had the Qt version number in the name, both
-in the module and the :rc:`backend` value
-(e.g. ``matplotlib.backends.backend_qt4agg`` and
-``matplotlib.backends.backend_qt5agg``). However as part of adding support for
-Qt6 we were able to support both Qt5 and Qt6 with a single implementation with
-all of the Qt version and binding support handled in
-`~matplotlib.backends.qt_compat`.  A majority of the renderer agnostic Qt code
-is now in `matplotlib.backends.backend_qt` with specialization for AGG in
-``backend_qtagg`` and cairo in ``backend_qtcairo``.
-
-The binding is selected at run time based on what bindings are already imported
-(by checking for the ``QtCore`` sub-package), then by the :envvar:`QT_API`
-environment variable, and finally by the :rc:`backend`.  In all cases when we
-need to search, the order is ``PyQt6``, ``PySide6``, ``PyQt5``, ``PySide2``.
-See :ref:`QT_API-usage` for usage instructions.
-
-The ``backend_qt5``, ``backend_qt5agg``, and ``backend_qt5cairo`` are provided
-and force the use of a Qt5 binding for backwards compatibility.  Their use is
-discouraged (but not deprecated) and ``backend_qt``, ``backend_qtagg``, or
-``backend_qtcairo`` should be preferred instead.  However, these modules will
-not be deprecated until we drop support for Qt5.
-
-
-
-
 .. [#] There is also `PyQt4
        <https://www.riverbankcomputing.com/static/Docs/PyQt4/>`_ and `PySide
        <https://srinikom.github.io/pyside-docs/>`_ for Qt4 but these are no

doc/api/backend_wx_api.rst

@@ -1,8 +1,8 @@
 :mod:`.backend_wxagg`, :mod:`.backend_wxcairo`
 ==============================================
 
-**NOTE** These backends are not documented here, to avoid adding a dependency
-to building the docs.
+**NOTE** These :ref:`backends` are not documented here, to avoid adding a
+dependency to building the docs.
 
 .. redirect-from:: /api/backend_wxagg_api
 

doc/users/explain/backends.rst

@@ -161,7 +161,9 @@ Backend   Description
 ========= ================================================================
 QtAgg     Agg rendering in a Qt_ canvas (requires PyQt_ or `Qt for Python`_,
           a.k.a. PySide).  This backend can be activated in IPython with
-          ``%matplotlib qt``.
+          ``%matplotlib qt``.  The Qt binding can be selected via the
+          :envvar:`QT_API` environment variable; see :ref:`QT_bindings` for
+          more details.
 ipympl    Agg rendering embedded in a Jupyter widget (requires ipympl_).
           This backend can be enabled in a Jupyter notebook with
           ``%matplotlib ipympl``.
@@ -229,23 +231,6 @@ or
 
 See `installing ipympl <https://matplotlib.org/ipympl/installing.html>`__ for more details.
 
-.. _QT_API-usage:
-
-How do I select the Qt implementation?
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The QtAgg and QtCairo backends support both Qt 5 and 6, as well as both Python
-bindings (`PyQt`_ or `Qt for Python`_, a.k.a. PySide). If any binding has
-already been loaded, then it will be used for the Qt backend. Otherwise, the
-first available binding is used, in the order: PyQt6, PySide6, PyQt5, PySide2.
-
-The :envvar:`QT_API` environment variable can be set to override the search
-when nothing has already been loaded. It may be set to (case-insensitively)
-PyQt6, PySide6, PyQt5, or PySide2 to pick the version and binding to use. If
-the chosen implementation is unavailable, the Qt backend will fail to load
-without attempting any other Qt implementations.  See :ref:`QT_bindings` for
-more details.
-
 Using non-builtin backends
 --------------------------
 More generally, any importable backend can be selected by using any of the

doc/users/faq/environment_variables_faq.rst

@@ -48,7 +48,7 @@ Environment variables
 .. envvar:: QT_API
 
    The Python Qt wrapper to prefer when using Qt-based backends. See :ref:`the
-   entry in the usage guide <QT_API-usage>` for more information.
+   entry in the usage guide <QT_bindings>` for more information.
 
 .. _setting-linux-osx-environment-variables:
 

doc/users/prev_whats_new/whats_new_3.5.0.rst

@@ -623,7 +623,7 @@ the Agg or Cairo renderers. Simultaneously, support for Qt4 has been dropped.
 Both Qt6 and Qt5 are supported by a combined backend (QtAgg or QtCairo), and
 the loaded version is determined by modules already imported, the
 :envvar:`QT_API` environment variable, and available packages. See
-:ref:`QT_API-usage` for details. The versioned Qt5 backend names (Qt5Agg or
+:ref:`QT_bindings` for details. The versioned Qt5 backend names (Qt5Agg or
 Qt5Cairo) remain supported for backwards compatibility.
 
 .. _PyQt6: https://www.riverbankcomputing.com/static/Docs/PyQt6/