DOC: Recommend constrained_layout over tight_layout (#29584)

timhoffm · Mecanerd · rcomer · web-flow · commit 293eff8a9a74 · 2025-02-28T11:51:08.000Z
* DOC: Recommend constrained_layout over tight_layout Closes #17339 by addressing the remaining open issue #17339 (comment). * Update lib/matplotlib/layout_engine.py Co-authored-by: Mecanerd <joshdonath23@hotmail.com> * Update galleries/users_explain/axes/tight_layout_guide.py Co-authored-by: Ruth Comer <10599679+rcomer@users.noreply.github.com> --------- Co-authored-by: Mecanerd <joshdonath23@hotmail.com> Co-authored-by: Ruth Comer <10599679+rcomer@users.noreply.github.com>
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
