Merge pull request #29691 from meeseeksmachine/auto-backport-of-pr-29584-on-v3.10.x

rcomer · web-flow · commit c38e0f7d7efb · 2025-02-28T14:34:52.000Z
Backport PR #29584 on branch v3.10.x (DOC: Recommend constrained_layout over tight_layout)
diff --git a/galleries/users_explain/axes/tight_layout_guide.py b/galleries/users_explain/axes/tight_layout_guide.py
@@ -9,15 +9,17 @@
 
 How to use tight-layout to fit plots within your figure cleanly.
 
+.. tip::
+
+   *tight_layout* was the first layout engine in Matplotlib. The more modern
+   and more capable :ref:`Constrained Layout <constrainedlayout_guide>` should
+   typically be used instead.
+
 *tight_layout* automatically adjusts subplot params so that the
 subplot(s) fits in to the figure area. This is an experimental
 feature and may not work for some cases. It only checks the extents
 of ticklabels, axis labels, and titles.
 
-An alternative to *tight_layout* is :ref:`constrained_layout
-<constrainedlayout_guide>`.
-
-
 Simple example
 ==============
 
diff --git a/lib/matplotlib/layout_engine.py b/lib/matplotlib/layout_engine.py
@@ -10,9 +10,14 @@
 layout engine while the figure is being created.  In particular, colorbars are
 made differently with different layout engines (for historical reasons).
 
-Matplotlib supplies two layout engines, `.TightLayoutEngine` and
-`.ConstrainedLayoutEngine`.  Third parties can create their own layout engine
-by subclassing `.LayoutEngine`.
+Matplotlib has two built-in layout engines:
+
+- `.TightLayoutEngine` was the first layout engine added to Matplotlib.
+  See also :ref:`tight_layout_guide`.
+- `.ConstrainedLayoutEngine` is more modern and generally gives better results.
+  See also :ref:`constrainedlayout_guide`.
+
+Third parties can create their own layout engine by subclassing `.LayoutEngine`.
 """
 
 from contextlib import nullcontext
