Merge pull request matplotlib#25109 from jklymak/doc-figure-cross-ref

DOC: add more cross-ref and explanatory image

Author: story645

doc/_static/FigureInline.png

@@ -34,23 +34,57 @@ using Matplotlib, and what :ref:`Backend <what-is-a-backend>` you are using.
 Notebooks and IDEs
 ------------------
 
+.. figure:: /_static/FigureInline.png
+    :alt: Image of figure generated in Jupyter Notebook with inline backend.
+    :width: 400
+
+    Screenshot of a `Jupyter Notebook <https://jupyter.org>`_, with a figure
+    generated via the default `inline
+    <https://github.com/ipython/matplotlib-inline>`_ backend.
+
+
 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
 by default trim or expand the figure size to have a tight box around Artists
-added to the Figure (see :ref:`saving_figures`, below).
+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.
+
+.. figure:: /_static/FigureNotebook.png
+    :alt: Image of figure generated in Jupyter Notebook with notebook
+          backend, including a toolbar.
+    :width: 400
+
+    Screenshot of a  Jupyter Notebook with an interactive figure generated via
+    the ``%matplotlib notebook`` magic.  Users should also try the similar
+    `widget <https://matplotlib.org/ipympl/>`_ backend if using `JupyterLab
+    <https://jupyterlab.readthedocs.io/en/stable/>`_.
+
+
+.. seealso::
+    :ref:`interactive_figures`.
 
 Standalone scripts and interactive use
 --------------------------------------
 
 If the user is on a client with a windowing system, there are a number of
 :ref:`Backends <what-is-a-backend>` that can be used to render the Figure to
-the screen, usually using a Python Qt, Tk, or Wx toolkit, though there is a native
-MacOS backend as well.  These are typically chosen either in the user's
-:ref:`matplotlibrc <customizing-with-matplotlibrc-files>`, or by calling
+the screen, usually using a Python Qt, Tk, or Wx toolkit, or the native MacOS
+backend.  These are typically chosen either in the user's :ref:`matplotlibrc
+<customizing-with-matplotlibrc-files>`, or by calling, for example,
 ``matplotlib.use('QtAgg')`` at the beginning of a session or script.
 
+.. figure:: /_static/FigureQtAgg.png
+    :alt: Image of figure generated from a script via the QtAgg backend.
+    :width: 370
+
+    Screenshot of a Figure generated via a python script and shown using the
+    QtAgg backend.
+
 When run from a script, or interactively (e.g. from an
 `iPython shell <https://https://ipython.readthedocs.io/en/stable/>`_) the Figure
 will not be shown until we call ``plt.show()``. The Figure will appear in
@@ -64,6 +98,9 @@ Note that if you are on a client that does not have access to a windowing
 system, the Figure will fallback to being drawn using the "Agg" backend, and
 cannot be viewed, though it can be :ref:`saved <saving_figures>`.
 
+.. seealso::
+    :ref:`interactive_figures`.
+
 .. _creating_figures:
 
 Creating Figures

doc/_static/FigureNotebook.png

@@ -3,6 +3,7 @@
 .. currentmodule:: matplotlib
 
 .. _mpl-shell:
+.. _interactive_figures:
 
 ===================
 Interactive figures
@@ -12,6 +13,10 @@ When working with data, interactivity can be invaluable. The pan/zoom and
 mouse-location tools built into the Matplotlib GUI windows are often sufficient, but
 you can also use the event system to build customized data exploration tools.
 
+.. seealso::
+    :ref:`figure_explanation`.
+
+
 Matplotlib ships with :ref:`backends <what-is-a-backend>` binding to
 several GUI toolkits (Qt, Tk, Wx, GTK, macOS, JavaScript) and third party
 packages provide bindings to `kivy
@@ -42,7 +47,9 @@ collected. `.Figure`\s can be closed and deregistered from `.pyplot` individuall
 `.pyplot.close`; all open `.Figure`\s can be closed via ``plt.close('all')``.
 
 
-For more discussion of Matplotlib's event system and integrated event loops, please read:
+.. seealso::
+
+   For more discussion of Matplotlib's event system and integrated event loops:
 
    - :ref:`interactive_figures_and_eventloops`
    - :ref:`event-handling-tutorial`
@@ -246,6 +253,7 @@ and your figures may not be responsive.  Please consult the
 documentation of your GUI toolkit for details.
 
 
+.. _jupyter_notebooks_jupyterlab:
 
 Jupyter Notebooks / JupyterLab
 ------------------------------

doc/_static/FigureQtAgg.png

@@ -13,8 +13,22 @@
 `SubplotParams`
     Control the default spacing between subplots.
 
-See :ref:`figure_explanation` for narrative on how figures are used in
-Matplotlib.
+Figures are typically created using pyplot methods `~.pyplot.figure`,
+`~.pyplot.subplots`, and `~.pyplot.subplot_mosaic`.
+
+.. plot::
+    :include-source:
+
+    fig, ax = plt.subplots(figsize=(2, 2), facecolor='lightskyblue',
+                           layout='constrained')
+    fig.suptitle('Figure')
+    ax.set_title('Axes', loc='left', fontstyle='oblique', fontsize='medium')
+
+Some situations call for directly instantiating a `~.figure.Figure` class,
+usually inside an application of some sort (see :ref:`user_interfaces` for a
+list of examples) .  More information about Figures can be found at
+:ref:`figure_explanation`.
+
 """
 
 from contextlib import ExitStack

doc/users/explain/figures.rst

@@ -32,6 +32,11 @@
 ax.plot([1, 2, 3, 4], [1, 4, 2, 3])  # Plot some data on the axes.
 
 # %%
+#
+# Note that to get this Figure to display, you may have to call ``plt.show()``,
+# depending on your backend.  For more details of Figures and backends, see
+# :ref:`figure_explanation`.
+#
 # .. _figure_parts:
 #
 # Parts of a Figure
@@ -54,12 +59,17 @@
 #    fig = plt.figure()  # an empty figure with no Axes
 #    fig, ax = plt.subplots()  # a figure with a single Axes
 #    fig, axs = plt.subplots(2, 2)  # a figure with a 2x2 grid of Axes
+#    # a figure with one axes on the left, and two on the right:
+#    fig, axs = plt.subplot_mosaic([['left', 'right-top'],
+#                                   ['left', 'right_bottom]])
 #
 # It is often convenient to create the Axes together with the Figure, but you
 # can also manually add Axes later on.  Note that many
 # :doc:`Matplotlib backends </users/explain/backends>` support zooming and
 # panning on figure windows.
 #
+# For more on Figures, see :ref:`figure_explanation`.
+#
 # :class:`~matplotlib.axes.Axes`
 # ------------------------------
 #