More concicse how to for subplot adjustment.

- Repurpose the example "Auto Subplots Adjust" to "Programmatically
  controlling subplot adjustment". The effect of the example has been
  largely superseeded by tight layout and constrained layout. It's still
  useful as an example of using advanced concepts in Matplotlib such as
  Bboxes, transforms, events.
- Remove "How-to: Move the edge of an axes to make room for tick labels"
  and move it's content to "Programmatically controlling subplot
  adjustment"
- Remove "How-to: Automatically make room for tick labels"
  This is basically a documentation of `subplots_adjust()`. It's
  sufficient to link there.
- Write a single new section "How to: "Make room for tick labels"
  that only links to manual adjustment / tight layout / constrained
  layout / "Programmatically controlling subplot adjustment"

Author: timhoffm

doc/faq/howto_faq.rst

@@ -137,106 +137,25 @@ The same can be done using the pgf backend::
 
     from matplotlib.backends.backend_pgf import PdfPages
 
-.. _howto-subplots-adjust:
 
-Move the edge of an axes to make room for tick labels
------------------------------------------------------
-
-For subplots, you can control the default spacing on the left, right,
-bottom, and top as well as the horizontal and vertical spacing between
-multiple rows and columns using the
-:meth:`matplotlib.figure.Figure.subplots_adjust` method (in pyplot it
-is :func:`~matplotlib.pyplot.subplots_adjust`).  For example, to move
-the bottom of the subplots up to make room for some rotated x tick
-labels::
+.. _howto-auto-adjust:
 
-    fig = plt.figure()
-    fig.subplots_adjust(bottom=0.2)
-    ax = fig.add_subplot(111)
+Make room for tick labels
+-------------------------
 
-You can control the defaults for these parameters in your
-:file:`matplotlibrc` file; see :doc:`/tutorials/introductory/customizing`.  For
-example, to make the above setting permanent, you would set::
-
-    figure.subplot.bottom : 0.2   # the bottom of the subplots of the figure
-
-The other parameters you can configure are, with their defaults
-
-*left*  = 0.125
-    the left side of the subplots of the figure
-*right* = 0.9
-    the right side of the subplots of the figure
-*bottom* = 0.1
-    the bottom of the subplots of the figure
-*top* = 0.9
-    the top of the subplots of the figure
-*wspace* = 0.2
-    the amount of width reserved for space between subplots,
-    expressed as a fraction of the average axis width
-*hspace* = 0.2
-    the amount of height reserved for space between subplots,
-    expressed as a fraction of the average axis height
-
-If you want additional control, you can create an
-:class:`~matplotlib.axes.Axes` using the
-:func:`~matplotlib.pyplot.axes` command (or equivalently the figure
-:meth:`~matplotlib.figure.Figure.add_axes` method), which allows you to
-specify the location explicitly::
-
-    ax = fig.add_axes([left, bottom, width, height])
-
-where all values are in fractional (0 to 1) coordinates.  See
-:doc:`/gallery/subplots_axes_and_figures/axes_demo` for an example of
-placing axes manually.
+By default, Matplotlib uses fixed percentage margins around subplots. This can
+lead to labels overlapping or being cut off at the figure boundary. There are
+multiple ways to fix this:
 
-.. _howto-auto-adjust:
+- Manually adapt the subplot parameters using `.Figure.subplots_adjust` /
+  `.pyplot.subplots_adjust`.
+- Use one of the automatic layout mechanisms:
 
-Automatically make room for tick labels
----------------------------------------
+  - constrained layout (:doc:`/tutorials/intermediate/constrainedlayout_guide`)
+  - tight layout (:doc:`/tutorials/intermediate/tight_layout_guide`)
 
-.. note::
-   This is now easier to handle than ever before.
-   Calling :func:`~matplotlib.pyplot.tight_layout` or alternatively using
-   ``constrained_layout=True`` argument in :func:`~matplotlib.pyplot.subplots`
-   can fix many common layout issues.  See the
-   :doc:`/tutorials/intermediate/tight_layout_guide` and
-   :doc:`/tutorials/intermediate/constrainedlayout_guide` for more details.
-
-   The information below is kept here in case it is useful for other
-   purposes.
-
-In most use cases, it is enough to simply change the subplots adjust
-parameters as described in :ref:`howto-subplots-adjust`.  But in some
-cases, you don't know ahead of time what your tick labels will be, or
-how large they will be (data and labels outside your control may be
-being fed into your graphing application), and you may need to
-automatically adjust your subplot parameters based on the size of the
-tick labels.  Any :class:`~matplotlib.text.Text` instance can report
-its extent in window coordinates (a negative x coordinate is outside
-the window), but there is a rub.
-
-The :class:`~matplotlib.backend_bases.RendererBase` instance, which is
-used to calculate the text size, is not known until the figure is
-drawn (:meth:`~matplotlib.figure.Figure.draw`).  After the window is
-drawn and the text instance knows its renderer, you can call
-:meth:`~matplotlib.text.Text.get_window_extent`.  One way to solve
-this chicken and egg problem is to wait until the figure is draw by
-connecting
-(:meth:`~matplotlib.backend_bases.FigureCanvasBase.mpl_connect`) to the
-"on_draw" signal (:class:`~matplotlib.backend_bases.DrawEvent`) and
-get the window extent there, and then do something with it, e.g., move
-the left of the canvas over; see :ref:`event-handling-tutorial`.
-
-Here is an example that gets a bounding box in relative figure coordinates
-(0..1) of each of the labels and uses it to move the left of the subplots
-over so that the tick labels fit in the figure:
-
-.. figure:: ../gallery/pyplots/images/sphx_glr_auto_subplots_adjust_001.png
-    :target: ../gallery/pyplots/auto_subplots_adjust.html
-    :align: center
-    :scale: 50
-
-    Auto Subplots Adjust
+- Calculate good values from the size of the plot elements yourself
+  (:doc:`/gallery/pyplots/auto_subplots_adjust`)
 
 .. _howto-align-label:
 

examples/pyplots/auto_subplots_adjust.py

@@ -1,15 +1,41 @@
 """
-====================
-Auto Subplots Adjust
-====================
+===============================================
+Programmatically controlling subplot adjustment
+===============================================
 
-Automatically adjust subplot parameters. This example shows a way to determine
-a subplot parameter from the extent of the ticklabels using a callback on the
-:doc:`draw_event</users/event_handling>`.
+.. note::
 
-Note that a similar result would be achieved using `~.Figure.tight_layout`
-or `~.Figure.set_constrained_layout`; this example shows how one could
-customize the subplot parameter adjustment.
+    This example is primarily intended to show some advanced concepts in
+    Matplotlib.
+
+    If you are only looking for having enough space for your labels, it is
+    almost always simpler and good enough to either set the subplot parameters
+    manually using `.Figure.subplots_adjust`, or use one of the automatic
+    layout mechanisms
+    (:doc:`/tutorials/intermediate/constrainedlayout_guide` or
+    :doc:`/tutorials/intermediate/tight_layout_guide`).
+
+This example describes a user-defined way to read out Artist sizes and
+set the subplot parameters accordingly. Its main purpose is to illustrate
+some advanced concepts like reading out text positions, working with
+bounding boxes and transforms and using
+:ref:`events <event-handling-tutorial>`. But it can also serve as a starting
+point if you want to automate the layouting and need more flexibility than
+tight layout and constrained layout.
+
+Below, we collect the bounding boxes of all y-labels and move the left border
+of the subplot to the right so that it leaves enough room for the union of all
+the bounding boxes.
+
+There's one catch with calculating text bounding boxes:
+Querying the text bounding boxes (`.Text.get_window_extent`) needs a
+renderer (`.RendererBase` instance), to calculate the text size. This renderer
+is only available after the figure has been drawn (`.Figure.draw`).
+
+A solution to this is putting the adjustment logic in a draw callback.
+This function is executed after the figure has been drawn. It can now check
+if the subplot leaves enough room for the text. If not, the subplot parameters
+are updated and second draw is triggered.
 """
 
 import matplotlib.pyplot as plt
@@ -24,15 +50,16 @@
 def on_draw(event):
     bboxes = []
     for label in labels:
-        bbox = label.get_window_extent()
-        # the figure transform goes from relative coords->pixels and we
-        # want the inverse of that
-        bboxi = bbox.transformed(fig.transFigure.inverted())
-        bboxes.append(bboxi)
+        # Bounding box in pixels
+        bbox_px = label.get_window_extent()
+        # Transform to relative figure coordinates. This is the inverse of
+        # transFigure.
+        bbox_fig = bbox_px.transformed(fig.transFigure.inverted())
+        bboxes.append(bbox_fig)
     # the bbox that bounds all the bboxes, again in relative figure coords
     bbox = mtransforms.Bbox.union(bboxes)
     if fig.subplotpars.left < bbox.width:
-        # we need to move it over
+        # Move the subplot left edge more to the right
         fig.subplots_adjust(left=1.1*bbox.width)  # pad a little
         fig.canvas.draw()
 

tutorials/intermediate/constrainedlayout_guide.py

@@ -77,10 +77,10 @@ def example_plot(ax, fontsize=12, hide_labels=False):
 
 ###############################################################################
 # To prevent this, the location of axes needs to be adjusted. For
-# subplots, this can be done by adjusting the subplot params
-# (:ref:`howto-subplots-adjust`). However, specifying your figure with the
-# ``constrained_layout=True`` keyword argument will do the adjusting
-# automatically.
+# subplots, this can be done manually by adjusting the subplot parameters
+# using `.Figure.subplots_adjust`. However, specifying your figure with the
+# # ``constrained_layout=True`` keyword argument will do the adjusting
+# # automatically.
 
 fig, ax = plt.subplots(constrained_layout=True)
 example_plot(ax, fontsize=24)

tutorials/intermediate/tight_layout_guide.py

@@ -46,9 +46,9 @@ def example_plot(ax, fontsize=12):
 
 ###############################################################################
 # To prevent this, the location of axes needs to be adjusted. For
-# subplots, this can be done by adjusting the subplot params
-# (:ref:`howto-subplots-adjust`). Matplotlib v1.1 introduced
-# `.Figure.tight_layout` that does this automatically for you.
+# subplots, this can be done manually by adjusting the subplot parameters
+# using `.Figure.subplots_adjust`. `.Figure.tight_layout` does this
+# automatically.
 
 fig, ax = plt.subplots()
 example_plot(ax, fontsize=24)