Update documentation

ianthomas23 · ianthomas23 · commit 828939fcff03 · 2024-04-26T12:06:28.000+01:00
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -95,7 +95,7 @@ jobs:
             python-version: '3.12'
             # https://bugreports.qt.io/projects/PYSIDE/issues/PYSIDE-2346
             pyside6-ver: '!=6.5.1'
-          # Temporary CI run using pre-release IPython and matplotlib-inline
+          # Temporary CI run using pre-release IPython
           - name-suffix: 'Pre-release IPython'
             os: ubuntu-22.04
             python-version: '3.12'
@@ -286,13 +286,12 @@ jobs:
             --index-url https://pypi.anaconda.org/scientific-python-nightly-wheels/simple \
             --upgrade --only-binary=:all: numpy pandas
 
-      - name: Install pre-release IPython and matplotlib-inline
+      - name: Install pre-release IPython
         if: matrix.name-suffix == 'Pre-release IPython'
         # Temporary, until release of IPython 8.24
         run: |
           pip list
-          pip install git+https://github.com/ianthomas23/ipython@entry_points
-          pip install git+https://github.com/ipython/matplotlib-inline@main
+          pip install git+https://github.com/ipython/ipython@main
           pip list
 
       - name: Install Matplotlib
diff --git a/doc/users/next_whats_new/backend_registry.rst b/doc/users/next_whats_new/backend_registry.rst
@@ -3,4 +3,15 @@ BackendRegistry
 
 New :class:`~matplotlib.backends.registry.BackendRegistry` class is the single
 source of truth for available backends. The singleton instance is
-``matplotlib.backends.backend_registry``.
+``matplotlib.backends.backend_registry``. It is used internally by Matplotlib,
+and also IPython (and therefore Jupyter) starting with IPython 8.24.0.
+
+There are three sources of backends: built-in (source code is within the
+Matplotlib repository), explicit ``module://some.backend`` syntax (backend is
+obtained by loading the module), or via an entry point (self-registering
+backend in an external package).
+
+To obtain a list of all registered backends use:
+
+    >>> from matplotlib.backends import backend_registry
+    >>> backend_registry.list_all()
diff --git a/galleries/users_explain/figure/backends.rst b/galleries/users_explain/figure/backends.rst
@@ -175,7 +175,8 @@ QtAgg     Agg rendering in a Qt_ canvas (requires PyQt_ or `Qt for Python`_,
           more details.
 ipympl    Agg rendering embedded in a Jupyter widget (requires ipympl_).
           This backend can be enabled in a Jupyter notebook with
-          ``%matplotlib ipympl``.
+          ``%matplotlib ipympl`` or ``%matplotlib widget``.  Works with
+          Jupyter ``lab`` and ``notebook>=7``.
 GTK3Agg   Agg rendering to a GTK_ 3.x canvas (requires PyGObject_ and
           pycairo_).  This backend can be activated in IPython with
           ``%matplotlib gtk3``.
@@ -188,7 +189,8 @@ TkAgg     Agg rendering to a 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``.
+          ``%matplotlib notebook`` or ``%matplotlib nbagg``.  Works with
+          Jupyter ``notebook<7`` and ``nbclassic``.
 WebAgg    On ``show()`` will start a tornado server with an interactive
           figure.
 GTK3Cairo Cairo rendering to a GTK_ 3.x canvas (requires PyGObject_ and
@@ -200,7 +202,7 @@ wxAgg     Agg rendering to a wxWidgets_ canvas (requires wxPython_ 4).
 ========= ================================================================
 
 .. note::
-   The names of builtin backends case-insensitive; e.g., 'QtAgg' and
+   The names of builtin backends are case-insensitive; e.g., 'QtAgg' and
    'qtagg' are equivalent.
 
 .. _`Anti-Grain Geometry`: http://agg.sourceforge.net/antigrain.com/
@@ -222,11 +224,13 @@ wxAgg     Agg rendering to a wxWidgets_ canvas (requires wxPython_ 4).
 .. _wxWidgets: https://www.wxwidgets.org/
 .. _ipympl: https://www.matplotlib.org/ipympl
 
+.. _ipympl_install:
+
 ipympl
 ^^^^^^
 
-The Jupyter widget ecosystem is moving too fast to support directly in
-Matplotlib.  To install ipympl:
+The ipympl backend is in a separate package that must be explicitly installed
+if you wish to use it, for example:
 
 .. code-block:: bash
 
diff --git a/galleries/users_explain/figure/figure_intro.rst b/galleries/users_explain/figure/figure_intro.rst
@@ -52,14 +52,20 @@ Notebooks and IDEs
 
 If you are using a Notebook (e.g. `Jupyter <https://jupyter.org>`_) or an IDE
 that renders Notebooks (PyCharm, VSCode, etc), then they have a backend that
-will render the Matplotlib Figure when a code cell is executed.  One thing to
-be aware of is that the default Jupyter backend (``%matplotlib inline``) will
+will render the Matplotlib Figure when a code cell is executed.  The default
+Jupyter backend (``%matplotlib inline``) creates static plots that
 by default trim or expand the figure size to have a tight box around Artists
-added to the Figure (see :ref:`saving_figures`, below).  If you use a backend
-other than the default "inline" backend, you will likely need to use an ipython
-"magic" like ``%matplotlib notebook`` for the Matplotlib :ref:`notebook
-<jupyter_notebooks_jupyterlab>` or ``%matplotlib widget`` for the  `ipympl
-<https://matplotlib.org/ipympl/>`_ backend.
+added to the Figure (see :ref:`saving_figures`, below).  For interactive plots
+in Jupyter you will need to use an ipython "magic" like ``%matplotlib widget``
+for the  `ipympl <https://matplotlib.org/ipympl/>`_ backend in ``jupyter lab``
+or ``notebook>=7``, or ``%matplotlib notebook`` for the Matplotlib
+:ref:`notebook <jupyter_notebooks_jupyterlab>` in ``notebook<7`` or
+``nbclassic``.
+
+.. note::
+
+    The  `ipympl <https://matplotlib.org/ipympl/>`_ backend is in a separate
+    package, see :ref:`Installing ipympl <ipympl_install>`.
 
 .. figure:: /_static/FigureNotebook.png
     :alt: Image of figure generated in Jupyter Notebook with notebook
@@ -75,15 +81,6 @@ other than the default "inline" backend, you will likely need to use an ipython
 .. seealso::
     :ref:`interactive_figures`.
 
-.. note::
-
-   If you only need to use the classic notebook (i.e. ``notebook<7``),
-   you can use:
-
-   .. sourcecode:: ipython
-
-   %matplotlib notebook
-
 .. _standalone-scripts-and-interactive-use:
 
 Standalone scripts and interactive use
@@ -104,7 +101,7 @@ backend.  These are typically chosen either in the user's :ref:`matplotlibrc
     QtAgg backend.
 
 When run from a script, or interactively (e.g. from an
-`iPython shell <https://ipython.readthedocs.io/en/stable/>`_) the Figure
+`IPython shell <https://ipython.readthedocs.io/en/stable/>`_) the Figure
 will not be shown until we call ``plt.show()``. The Figure will appear in
 a new GUI window, and usually will have a toolbar with Zoom, Pan, and other tools
 for interacting with the Figure.  By default, ``plt.show()`` blocks
diff --git a/galleries/users_explain/figure/writing_a_backend_pyplot_interface.rst b/galleries/users_explain/figure/writing_a_backend_pyplot_interface.rst
@@ -84,3 +84,47 @@ Function-based API
 2. **Showing figures**: `.pyplot.show()` calls a module-level ``show()``
    function, which is typically generated via the ``ShowBase`` class and its
    ``mainloop`` method.
+
+Registering a backend
+---------------------
+
+For a new backend to be usable via ``matplotlib.use()`` or IPython
+``%matplotlib`` magic command, it must be compatible with one of the three ways
+supported by the :class:`~matplotlib.backends.registry.BackendRegistry`:
+
+Built-in
+^^^^^^^^
+
+A backend built into Matplotlib must have its name and
+``FigureCanvas.required_interactive_framework`` hard-coded in the
+:class:`~matplotlib.backends.registry.BackendRegistry`.  If the backend module
+is not ``f"matplotlib.backends.backend_{backend_name.lower()}"`` then there
+must also be an entry in the ``BackendRegistry._name_to_module``.
+
+module:// syntax
+^^^^^^^^^^^^^^^^
+
+Any backend in a separate module (not built into Matplotlib) can be used by
+specifying the path to the module in the form ``module://some.backend.module``.
+An example is ``module://mplcairo.qt`` for
+`mplcairo <https:////github.com/matplotlib/mplcairo>`_.  The backend's
+interactive framework will be taken from its
+``FigureCanvas.required_interactive_framework``.
+
+Entry point
+^^^^^^^^^^^
+
+An external backend module can self-register as a backend using an
+``entry point`` in its ``pyproject.toml`` such as the one used by
+``matplotlib-inline``:
+
+.. code-block:: toml
+
+    [project.entry-points."matplotlib.backend"]
+    inline = "matplotlib_inline.backend_inline"
+
+The backend's interactive framework will be taken from its
+``FigureCanvas.required_interactive_framework``.  All entry points are loaded
+together but only when first needed, such as when a backend name is not
+recognised as a built-in backend, or when
+:meth:`~matplotlib.backends.registry.BackendRegistry.list_all` is first called.
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -1766,6 +1766,10 @@ def _fix_ipython_backend2gui(cls):
         # `ipython --auto`).  This cannot be done at import time due to
         # ordering issues, so we do it when creating a canvas, and should only
         # be done once per class (hence the `cache`).
+
+        # This function will not be needed when Python 3.12, the latest version
+        # supported by IPython < 8.24, reaches end-of-life in late 2028.
+        # At that time this function can be made a no-op and deprecated.
         mod_ipython = sys.modules.get("IPython")
         if mod_ipython is None or mod_ipython.version_info[:2] >= (8, 24):
             # Use of backend2gui is not needed for IPython >= 8.24 as the
diff --git a/lib/matplotlib/backends/registry.py b/lib/matplotlib/backends/registry.py
@@ -24,7 +24,7 @@ class BackendRegistry:
     Each backend has a name, a module name containing the backend code, and an
     optional GUI framework that must be running if the backend is interactive.
     There are three sources of backends: built-in (source code is within the
-    Matplotlib repository), explicit module://some.backend syntax (backend is
+    Matplotlib repository), explicit ``module://some.backend`` syntax (backend is
     obtained by loading the module), or via an entry point (self-registering
     backend in an external package).
 
@@ -208,7 +208,7 @@ def is_valid_backend(self, backend: str) -> bool:
         Return True if the backend name is valid, False otherwise.
 
         A backend name is valid if it is one of the built-in backends or has been
-        dynamically added via an entry point. Those beginning with "module://" are
+        dynamically added via an entry point. Those beginning with ``module://`` are
         always considered valid and are added to the current list of all backends
         within this function.
 
@@ -256,14 +256,14 @@ def list_all(self):
         Return list of all known backends.
 
         These include built-in backends and those obtained at runtime either from entry
-        points or explicit module://some.backend syntax.
+        points or explicit ``module://some.backend`` syntax.
+
+        Entry points will be loaded if they haven't been already.
 
         Returns
         -------
         list of str
             Backend names.
-
-        Entry points will be loaded if they haven't been already.
         """
         self._ensure_entry_points_loaded()
         return self.list_builtin() + list(self._backend_to_gui_framework.keys())
@@ -323,12 +323,15 @@ def load_backend_module(self, backend):
 
     def resolve_backend(self, backend):
         """
-        Return the backend and GUI framework for the specified backend.
+        Return the backend and GUI framework for the specified backend name.
 
         If the GUI framework is not yet known then it will be determine by loading the
-        backend module and checking the FigureCanvas.required_interactive_framework
+        backend module and checking the ``FigureCanvas.required_interactive_framework``
         attribute.
 
+        This function only loads entry points if they have not already been loaded and
+        the backend is not built-in and not of ``module://some.backend`` format.
+
         Parameters
         ----------
         backend : str or None
@@ -339,9 +342,6 @@ def resolve_backend(self, backend):
         Tuple of backend (str) and GUI framework (str or None).
             A non-interactive backend returns None for its GUI framework rather than
             "headless".
-
-        This function only loads entry points if they have not already been loaded and
-        the backend is not built-in and not of module://some.backend format.
         """
         if isinstance(backend, str):
             backend = backend.lower()
@@ -380,10 +380,11 @@ def resolve_gui_or_backend(self, gui_or_backend):
         either a GUI framework or a backend name, tested in that order.
 
         This is for use with the IPython %matplotlib magic command which may be a GUI
-        framework such as
-            %matplotlib qt
-        or a backend name such as
-            %matplotlib qtagg
+        framework such as ``%matplotlib qt`` or a backend name such as
+        ``%matplotlib qtagg``.
+
+        This function only loads entry points if they have not already been loaded and
+        the backend is not built-in and not of ``module://some.backend`` format.
 
         Parameters
         ----------
@@ -395,9 +396,6 @@ def resolve_gui_or_backend(self, gui_or_backend):
         Tuple of backend (str) and GUI framework (str or None).
             A non-interactive backend returns None for its GUI framework rather than
             "headless".
-
-        This function only loads entry points if they have not already been loaded and
-        the backend is not built-in and not of module://some.backend format.
         """
         gui_or_backend = gui_or_backend.lower()
 
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -298,6 +298,8 @@ def install_repl_displayhook() -> None:
     if mod_ipython.version_info[:2] < (8, 24):
         # Use of backend2gui is not needed for IPython >= 8.24 as that functionality
         # has been moved to Matplotlib.
+        # This code can be removed when Python 3.12, the latest version supported by
+        # IPython < 8.24, reaches end-of-life in late 2028.
         from IPython.core.pylabtools import backend2gui
         # trigger IPython's eventloop integration, if available
         ipython_gui_name = backend2gui.get(get_backend())
diff --git a/lib/matplotlib/testing/__init__.py b/lib/matplotlib/testing/__init__.py
@@ -190,6 +190,8 @@ def ipython_in_subprocess(
     if IPython.version_info[:2] >= (8, 24):
         expected_backend = expected_backend_new_ipython
     else:
+        # This code can be removed when Python 3.12, the latest version supported by
+        # IPython < 8.24, reaches end-of-life in late 2028.
         expected_backend = expected_backend_old_ipython
 
     code = ("import matplotlib as mpl, matplotlib.pyplot as plt;"
diff --git a/lib/matplotlib/tests/test_backend_inline.py b/lib/matplotlib/tests/test_backend_inline.py
@@ -35,6 +35,8 @@ def test_ipynb():
     if IPython.version_info[:2] >= (8, 24):
         expected_backend = "inline"
     else:
+        # This code can be removed when Python 3.12, the latest version supported by
+        # IPython < 8.24, reaches end-of-life in late 2028.
         expected_backend = "module://matplotlib_inline.backend_inline"
     backend_outputs = nb.cells[2]["outputs"]
     assert backend_outputs[0]["data"]["text/plain"] == f"'{expected_backend}'"
diff --git a/lib/matplotlib/tests/test_backend_nbagg.py b/lib/matplotlib/tests/test_backend_nbagg.py
@@ -35,6 +35,8 @@ def test_ipynb():
     if IPython.version_info[:2] >= (8, 24):
         expected_backend = "notebook"
     else:
+        # This code can be removed when Python 3.12, the latest version supported by
+        # IPython < 8.24, reaches end-of-life in late 2028.
         expected_backend = "nbAgg"
     backend_outputs = nb.cells[2]["outputs"]
     assert backend_outputs[0]["data"]["text/plain"] == f"'{expected_backend}'"
