Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 76dd07e

Browse files
story645story645
authored
Merge pull request matplotlib#25109 from jklymak/doc-figure-cross-ref
DOC: add more cross-ref and explanatory image
2 parents 71a8998 + 4f12d48 commit 76dd07e

File tree

7 files changed

+76
-7
lines changed

7 files changed

+76
-7
lines changed

‎doc/_static/FigureInline.png

425 KB
Loading

‎doc/_static/FigureNotebook.png

429 KB
Loading

‎doc/_static/FigureQtAgg.png

862 KB
Loading

‎doc/users/explain/figures.rst

Lines changed: 41 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -34,23 +34,57 @@ using Matplotlib, and what :ref:`Backend <what-is-a-backend>` you are using.
3434
Notebooks and IDEs
3535
------------------
3636

37+
.. figure:: /_static/FigureInline.png
38+
:alt: Image of figure generated in Jupyter Notebook with inline backend.
39+
:width: 400
40+
41+
Screenshot of a `Jupyter Notebook <https://jupyter.org>`_, with a figure
42+
generated via the default `inline
43+
<https://github.com/ipython/matplotlib-inline>`_ backend.
44+
45+
3746
If you are using a Notebook (e.g. `Jupyter <https://jupyter.org>`_) or an IDE
3847
that renders Notebooks (PyCharm, VSCode, etc), then they have a backend that
3948
will render the Matplotlib Figure when a code cell is executed. One thing to
4049
be aware of is that the default Jupyter backend (``%matplotlib inline``) will
4150
by default trim or expand the figure size to have a tight box around Artists
42-
added to the Figure (see :ref:`saving_figures`, below).
51+
added to the Figure (see :ref:`saving_figures`, below). If you use a backend
52+
other than the default "inline" backend, you will likely need to use an ipython
53+
"magic" like ``%matplotlib notebook`` for the Matplotlib :ref:`notebook
54+
<jupyter_notebooks_jupyterlab>` or ``%matplotlib widget`` for the `ipympl
55+
<https://matplotlib.org/ipympl/>`_ backend.
56+
57+
.. figure:: /_static/FigureNotebook.png
58+
:alt: Image of figure generated in Jupyter Notebook with notebook
59+
backend, including a toolbar.
60+
:width: 400
61+
62+
Screenshot of a Jupyter Notebook with an interactive figure generated via
63+
the ``%matplotlib notebook`` magic. Users should also try the similar
64+
`widget <https://matplotlib.org/ipympl/>`_ backend if using `JupyterLab
65+
<https://jupyterlab.readthedocs.io/en/stable/>`_.
66+
67+
68+
.. seealso::
69+
:ref:`interactive_figures`.
4370

4471
Standalone scripts and interactive use
4572
--------------------------------------
4673

4774
If the user is on a client with a windowing system, there are a number of
4875
:ref:`Backends <what-is-a-backend>` that can be used to render the Figure to
49-
the screen, usually using a Python Qt, Tk, or Wx toolkit, though there is a native
50-
MacOS backend as well. These are typically chosen either in the user's
51-
:ref:`matplotlibrc <customizing-with-matplotlibrc-files>`, or by calling
76+
the screen, usually using a Python Qt, Tk, or Wx toolkit, or the native MacOS
77+
backend. These are typically chosen either in the user's :ref:`matplotlibrc
78+
<customizing-with-matplotlibrc-files>`, or by calling, for example,
5279
``matplotlib.use('QtAgg')`` at the beginning of a session or script.
5380

81+
.. figure:: /_static/FigureQtAgg.png
82+
:alt: Image of figure generated from a script via the QtAgg backend.
83+
:width: 370
84+
85+
Screenshot of a Figure generated via a python script and shown using the
86+
QtAgg backend.
87+
5488
When run from a script, or interactively (e.g. from an
5589
`iPython shell <https://https://ipython.readthedocs.io/en/stable/>`_) the Figure
5690
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
6498
system, the Figure will fallback to being drawn using the "Agg" backend, and
6599
cannot be viewed, though it can be :ref:`saved <saving_figures>`.
66100

101+
.. seealso::
102+
:ref:`interactive_figures`.
103+
67104
.. _creating_figures:
68105

69106
Creating Figures

‎doc/users/explain/interactive.rst

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
.. currentmodule:: matplotlib
44

55
.. _mpl-shell:
6+
.. _interactive_figures:
67

78
===================
89
Interactive figures
@@ -12,6 +13,10 @@ When working with data, interactivity can be invaluable. The pan/zoom and
1213
mouse-location tools built into the Matplotlib GUI windows are often sufficient, but
1314
you can also use the event system to build customized data exploration tools.
1415

16+
.. seealso::
17+
:ref:`figure_explanation`.
18+
19+
1520
Matplotlib ships with :ref:`backends <what-is-a-backend>` binding to
1621
several GUI toolkits (Qt, Tk, Wx, GTK, macOS, JavaScript) and third party
1722
packages provide bindings to `kivy
@@ -42,7 +47,9 @@ collected. `.Figure`\s can be closed and deregistered from `.pyplot` individuall
4247
`.pyplot.close`; all open `.Figure`\s can be closed via ``plt.close('all')``.
4348

4449

45-
For more discussion of Matplotlib's event system and integrated event loops, please read:
50+
.. seealso::
51+
52+
For more discussion of Matplotlib's event system and integrated event loops:
4653

4754
- :ref:`interactive_figures_and_eventloops`
4855
- :ref:`event-handling-tutorial`
@@ -246,6 +253,7 @@ and your figures may not be responsive. Please consult the
246253
documentation of your GUI toolkit for details.
247254

248255

256+
.. _jupyter_notebooks_jupyterlab:
249257

250258
Jupyter Notebooks / JupyterLab
251259
------------------------------

‎lib/matplotlib/figure.py

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,22 @@
1313
`SubplotParams`
1414
Control the default spacing between subplots.
1515
16-
See :ref:`figure_explanation` for narrative on how figures are used in
17-
Matplotlib.
16+
Figures are typically created using pyplot methods `~.pyplot.figure`,
17+
`~.pyplot.subplots`, and `~.pyplot.subplot_mosaic`.
18+
19+
.. plot::
20+
:include-source:
21+
22+
fig, ax = plt.subplots(figsize=(2, 2), facecolor='lightskyblue',
23+
layout='constrained')
24+
fig.suptitle('Figure')
25+
ax.set_title('Axes', loc='left', fontstyle='oblique', fontsize='medium')
26+
27+
Some situations call for directly instantiating a `~.figure.Figure` class,
28+
usually inside an application of some sort (see :ref:`user_interfaces` for a
29+
list of examples) . More information about Figures can be found at
30+
:ref:`figure_explanation`.
31+
1832
"""
1933

2034
from contextlib import ExitStack

‎tutorials/introductory/quick_start.py

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,11 @@
3232
ax.plot([1, 2, 3, 4], [1, 4, 2, 3]) # Plot some data on the axes.
3333

3434
# %%
35+
#
36+
# Note that to get this Figure to display, you may have to call ``plt.show()``,
37+
# depending on your backend. For more details of Figures and backends, see
38+
# :ref:`figure_explanation`.
39+
#
3540
# .. _figure_parts:
3641
#
3742
# Parts of a Figure
@@ -54,12 +59,17 @@
5459
# fig = plt.figure() # an empty figure with no Axes
5560
# fig, ax = plt.subplots() # a figure with a single Axes
5661
# fig, axs = plt.subplots(2, 2) # a figure with a 2x2 grid of Axes
62+
# # a figure with one axes on the left, and two on the right:
63+
# fig, axs = plt.subplot_mosaic([['left', 'right-top'],
64+
# ['left', 'right_bottom]])
5765
#
5866
# It is often convenient to create the Axes together with the Figure, but you
5967
# can also manually add Axes later on. Note that many
6068
# :doc:`Matplotlib backends </users/explain/backends>` support zooming and
6169
# panning on figure windows.
6270
#
71+
# For more on Figures, see :ref:`figure_explanation`.
72+
#
6373
# :class:`~matplotlib.axes.Axes`
6474
# ------------------------------
6575
#

0 commit comments

Comments
 (0)