diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index a83a25825ba5..f466c87bce62 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -2212,22 +2212,22 @@ def __init__(self, The use of this parameter is discouraged. Please use ``layout='constrained'`` instead. - layout : {'constrained', 'tight'}, optional - The layout mechanism for positioning of plot elements. - Supported values: + layout : {'constrained', 'tight'}, optional, default: None + The layout mechanism for positioning of plot elements to avoid + overlapping Axes decorations (labels, ticks, etc). Note that + layout managers can have significant performance penalties. - - 'constrained': The constrained layout solver usually gives the - best layout results and is thus recommended. However, it is - computationally expensive and can be slow for complex figures - with many elements. + - 'constrained': The constrained layout solver adjusts axes sizes + to avoid overlapping axes decorations. Can handle complex plot + layouts and colorbars, and is thus recommended. See :doc:`/tutorials/intermediate/constrainedlayout_guide` for examples. - 'tight': Use the tight layout mechanism. This is a relatively - simple algorithm, that adjusts the subplot parameters so that - decorations like tick labels, axis labels and titles have enough - space. See `.Figure.set_tight_layout` for further details. + simple algorithm that adjusts the subplot parameters so that + decorations do not overlap. See `.Figure.set_tight_layout` for + further details. If not given, fall back to using the parameters *tight_layout* and *constrained_layout*, including their config defaults diff --git a/tutorials/intermediate/constrainedlayout_guide.py b/tutorials/intermediate/constrainedlayout_guide.py index 7b296f99305d..d191a57d6409 100644 --- a/tutorials/intermediate/constrainedlayout_guide.py +++ b/tutorials/intermediate/constrainedlayout_guide.py @@ -29,15 +29,6 @@ Those are described in detail throughout the following sections. -.. warning:: - - Currently Constrained Layout is **experimental**. The - behaviour and API are subject to change, or the whole functionality - may be removed without a deprecation period. If you *require* your - plots to be absolutely reproducible, get the Axes positions after - running Constrained Layout and use ``ax.set_position()`` in your code - with ``constrained_layout=False``. - Simple Example ==============