DOC: cleanup constrained layout tutorial

jklymak · jklymak · commit 6df770669f90 · 2023-02-04T16:10:50.000-08:00
diff --git a/examples/subplots_axes_and_figures/colorbar_placement.py b/examples/subplots_axes_and_figures/colorbar_placement.py
@@ -1,4 +1,6 @@
 """
+.. _colorbar_placement:
+
 =================
 Placing Colorbars
 =================
diff --git a/tutorials/intermediate/constrainedlayout_guide.py b/tutorials/intermediate/constrainedlayout_guide.py
@@ -3,38 +3,46 @@
 Constrained Layout Guide
 ================================
 
-How to use constrained-layout to fit plots within your figure cleanly.
+Use *constrained layout* to fit plots within your figure cleanly.
 
-*constrained_layout* automatically adjusts subplots and decorations like
-legends and colorbars so that they fit in the figure window while still
-preserving, as best they can, the logical layout requested by the user.
+*Constrained layout* automatically adjusts subplots so that decorations like tick
+labels, legends, and colorbars do not overlap, while still preserving the
+logical layout requested by the user.
 
-*constrained_layout* is similar to
-:doc:`tight_layout</tutorials/intermediate/tight_layout_guide>`,
-but uses a constraint solver to determine the size of axes that allows
-them to fit.
+*Constrained layout* is similar to :doc:`Tight
+layout</tutorials/intermediate/tight_layout_guide>`, but is substantially more
+flexible.  It handles colorbars placed on multiple axes
+(:ref:`colorbar_placement`) nested layouts (`~.Figure.subfigures`) and Axes that
+span rows or columns (`~.pyplot.subplot_mosaic`), striving to align spines from
+axes in the same row or column.  In addition, :ref:`Compressed layout
+<compressed_layout>` will try and move fixed aspect-ratio axes closer together.
+These features are described in this document, as well as some
+:ref:`implementation details <cl_notes_on_algorithm>` discussed at the end.
 
-*constrained_layout* typically needs to be activated before any axes are
-added to a figure. Two ways of doing so are
+*Constrained layout* typically needs to be activated before any axes are added to
+a figure. Two ways of doing so are
 
 * using the respective argument to :func:`~.pyplot.subplots` or
   :func:`~.pyplot.figure`, e.g.::
 
       plt.subplots(layout="constrained")
 
-* activate it via :ref:`rcParams<customizing-with-dynamic-rc-settings>`,
-  like::
+* activate it via :ref:`rcParams<customizing-with-dynamic-rc-settings>`, like::
 
       plt.rcParams['figure.constrained_layout.use'] = True
 
 Those are described in detail throughout the following sections.
 
-Simple Example
+.. warning::
+
+    Calling ``plt.tight_layout()`` will turn off *constrained layout*!
+
+Simple example
 ==============
 
 In Matplotlib, the location of axes (including subplots) are specified in
-normalized figure coordinates. It can happen that your axis labels or
-titles (or sometimes even ticklabels) go outside the figure area, and are thus
+normalized figure coordinates. It can happen that your axis labels or titles
+(or sometimes even ticklabels) go outside the figure area, and are thus
 clipped.
 """
 
@@ -93,21 +101,19 @@ def example_plot(ax, fontsize=12, hide_labels=False):
     example_plot(ax)
 
 # %%
+#
 # Colorbars
 # =========
 #
-# If you create a colorbar with `.Figure.colorbar`,
-# you need to make room for it.  ``constrained_layout`` does this
-# automatically.  Note that if you specify ``use_gridspec=True`` it will be
-# ignored because this option is made for improving the layout via
-# ``tight_layout``.
+# If you create a colorbar with `.Figure.colorbar`, you need to make room for
+# it.  *Constrained layout* does this automatically.  Note that if you
+# specify ``use_gridspec=True`` it will be ignored because this option is made
+# for improving the layout via ``tight_layout``.
 #
 # .. note::
 #
 #   For the `~.axes.Axes.pcolormesh` keyword arguments (``pc_kwargs``) we use a
-#   dictionary. Below we will assign one colorbar to a number of axes each
-#   containing a `~.cm.ScalarMappable`; specifying the norm and colormap
-#   ensures the colorbar is accurate for all the axes.
+#   dictionary to keep the calls consistent across this document.
 
 arr = np.arange(100).reshape((10, 10))
 norm = mcolors.Normalize(vmin=0., vmax=100.)
@@ -142,7 +148,7 @@ def example_plot(ax, fontsize=12, hide_labels=False):
 # Suptitle
 # =========
 #
-# ``constrained_layout`` can also make room for `~.Figure.suptitle`.
+# *Constrained layout* can also make room for `~.Figure.suptitle`.
 
 fig, axs = plt.subplots(2, 2, figsize=(4, 4), layout="constrained")
 for ax in axs.flat:
@@ -234,7 +240,7 @@ def example_plot(ax, fontsize=12, hide_labels=False):
 #
 
 # %%
-# Padding and Spacing
+# Padding and spacing
 # ===================
 #
 # Padding between axes is controlled in the horizontal by *w_pad* and
@@ -274,7 +280,7 @@ def example_plot(ax, fontsize=12, hide_labels=False):
 
 # %%
 # GridSpecs also have optional *hspace* and *wspace* keyword arguments,
-# that will be used instead of the pads set by ``constrained_layout``:
+# that will be used instead of the pads set by *constrained layout*:
 
 fig, axs = plt.subplots(2, 2, layout="constrained",
                         gridspec_kw={'wspace': 0.3, 'hspace': 0.2})
@@ -424,7 +430,7 @@ def example_plot(ax, fontsize=12, hide_labels=False):
 
 # %%
 # Rather than using subgridspecs, Matplotlib now provides `~.Figure.subfigures`
-# which also work with ``constrained_layout``:
+# which also work with *constrained layout*:
 
 fig = plt.figure(layout="constrained")
 sfigs = fig.subfigures(1, 2, width_ratios=[1, 2])
@@ -448,7 +454,7 @@ def example_plot(ax, fontsize=12, hide_labels=False):
 #
 # There can be good reasons to manually set an Axes position.  A manual call
 # to `~.axes.Axes.set_position` will set the axes so constrained_layout has
-# no effect on it anymore. (Note that ``constrained_layout`` still leaves the
+# no effect on it anymore. (Note that *constrained layout* still leaves the
 # space for the axes that is moved).
 
 fig, axs = plt.subplots(1, 2, layout="constrained")
@@ -461,7 +467,7 @@ def example_plot(ax, fontsize=12, hide_labels=False):
 # Grids of fixed aspect-ratio Axes: "compressed" layout
 # =====================================================
 #
-# ``constrained_layout`` operates on the grid of "original" positions for
+# *Constrained layout* operates on the grid of "original" positions for
 # axes. However, when Axes have fixed aspect ratios, one side is usually made
 # shorter, and leaves large gaps in the shortened direction. In the following,
 # the Axes are square, but the figure quite wide so there is a horizontal gap:
@@ -485,17 +491,17 @@ def example_plot(ax, fontsize=12, hide_labels=False):
 
 
 # %%
-# Manually turning off ``constrained_layout``
+# Manually turning off *constrained layout*
 # ===========================================
 #
-# ``constrained_layout`` usually adjusts the axes positions on each draw
+# *Constrained layout* usually adjusts the axes positions on each draw
 # of the figure.  If you want to get the spacing provided by
-# ``constrained_layout`` but not have it update, then do the initial
+# *Constrained layout* but not have it update, then do the initial
 # draw and then call ``fig.set_layout_engine(None)``.
 # This is potentially useful for animations where the tick labels may
 # change length.
 #
-# Note that ``constrained_layout`` is turned off for ``ZOOM`` and ``PAN``
+# Note that *Constrained layout* is turned off for ``ZOOM`` and ``PAN``
 # GUI events for the backends that use the toolbar.  This prevents the
 # axes from changing position during zooming and panning.
 #
@@ -506,11 +512,11 @@ def example_plot(ax, fontsize=12, hide_labels=False):
 # Incompatible functions
 # ----------------------
 #
-# ``constrained_layout`` will work with `.pyplot.subplot`, but only if the
+# *Constrained layout* will work with `.pyplot.subplot`, but only if the
 # number of rows and columns is the same for each call.
 # The reason is that each call to `.pyplot.subplot` will create a new
 # `.GridSpec` instance if the geometry is not the same, and
-# ``constrained_layout``.  So the following works fine:
+# *Constrained layout*.  So the following works fine:
 
 fig = plt.figure(layout="constrained")
 
@@ -557,10 +563,10 @@ def example_plot(ax, fontsize=12, hide_labels=False):
 fig.suptitle('subplot2grid')
 
 # %%
-# Other Caveats
+# Other caveats
 # -------------
 #
-# * ``constrained_layout`` only considers ticklabels, axis labels, titles, and
+# * *Constrained layout* only considers ticklabels, axis labels, titles, and
 #   legends.  Thus, other artists may be clipped and also may overlap.
 #
 # * It assumes that the extra space needed for ticklabels, axis labels,
@@ -595,6 +601,8 @@ def example_plot(ax, fontsize=12, hide_labels=False):
 # not require outside data or dependencies (other than numpy).
 
 # %%
+# .. _cl_notes_on_algorithm:
+#
 # Notes on the algorithm
 # ======================
 #
@@ -691,7 +699,7 @@ def example_plot(ax, fontsize=12, hide_labels=False):
 # is a conscious decision of the algorithm, and leads to the case where
 # the two right-hand axes have the same height, but it is not 1/2 the height
 # of the left-hand axes.  This is consistent with how ``gridspec`` works
-# without constrained layout.
+# without *constrained layout*.
 
 fig = plt.figure(layout="constrained")
 gs = gridspec.GridSpec(2, 2, figure=fig)
