DOC: new Adding Artists, and modify pyplot instantiation discussion [skip actions] [skip appveyor] [skip azp]

jklymak · jklymak · commit f9ecd2f20451 · 2023-01-18T09:19:15.000-08:00
diff --git a/doc/users/explain/figures.rst b/doc/users/explain/figures.rst
@@ -14,9 +14,10 @@ Creating, viewing, and saving Matplotlib Figures
 When looking at Matplotlib visualization, you are almost always looking at
 Artists placed on a `~.Figure`.  In the example above, the figure is the
 gray region and `~.Figure.add_subplot` has added an `~.axes.Axes` artist to the
-`~.Figure` (see :ref:`figure_parts`).  A more complicated visualization can add multiple Axes to
-the Figure, colorbars, legends, annotations, and the Axes theselves can have
-multiple Artists added to them (e.g. ``ax.plot`` or ``ax.imshow``).
+`~.Figure` (see :ref:`figure_parts`).  A more complicated visualization can add
+multiple Axes to the Figure, colorbars, legends, annotations, and the Axes
+themselves can have multiple Artists added to them
+(e.g. ``ax.plot`` or ``ax.imshow``).
 
 .. _viewing_figures:
 
@@ -70,8 +71,9 @@ By far the most common way to create a figure is using the
 :ref:`api_interfaces`, the pyplot interface serves two purposes.  One is to spin
 up the Backend and keep track of GUI windows. The other is a global state for
 Axes and Artists that allow a short-form API to plotting methods. In the
-example above, we only use pyplot for the first purpose, to create the Figure
-object, ``fig``.
+example above, we use pyplot for the first purpose, and create the Figure object,
+``fig``. As a side effect ``fig`` is also added to pyplot's global state, and
+can be accessed via `~.pyplot.gcf`.
 
 In addition to `~.pyplot.figure`, there are convenience methods to create Axes
 at the same time that the figure is created since these two actions are so commonly
@@ -144,6 +146,25 @@ rescale axes inside the Figure to prevent overlap of ticklabels, and try and ali
 axes, and can save significant manual adjustment of artists on a Figure for many
 common cases.
 
+Adding Artists
+--------------
+
+The `~.FigureBase` class has a number of methods to add artists to a `~.Figure` or
+a `~.SubFigure`.  By far the most common are to add Axes of various configurations
+(`~.FigureBase.add_axes`, `~.FigureBase.add_subplot`, `~.FigureBase.subplots`,
+`~.FigureBase.subplot_mosaic`) and subfigures (`~.FigureBase.subfigures`).  Colorbars
+are added to Axes or group of Axes at the Figure level (`~.FigureBase.colorbar`).
+It is also possible to have a Figure-level legend (`~.FigureBase.legend`).
+Other Artists include figure-wide labels (`~.suptitle`,
+`~.subxlabel`, `~.subpylabel`) and text (`~.FigureBase.text`).  Finally, low-level
+Artists can be added directly using `~.FigureBase.add_artist` usually with care being
+taken to use the appropriate transform.  Usually these include ``Figure.transFigure``
+which ranges from 0 to 1 in each direction, and represents the fraction of the current
+Figure size, or ``Figure.dpi_scale_trans`` which will be in physical units of inches
+from the bottom left corner of the Figure (see
+:doc:`/tutorials/advanced/transforms_tutorial` for more details).
+
+
 .. _saving_figures:
 
 Saving Figures
