diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index 5b26f72845c9..10a407232827 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -2420,15 +2420,15 @@ def __init__(self, The use of this parameter is discouraged. Please use ``layout='constrained'`` instead. - layout : {'constrained', 'compressed', 'tight', `.LayoutEngine`, None} + layout : {'constrained', 'compressed', 'tight', 'none', `.LayoutEngine`, \ +None}, 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. - Defaults to *None*. - 'constrained': The constrained layout solver adjusts axes sizes - to avoid overlapping axes decorations. Can handle complex plot - layouts and colorbars, and is thus recommended. + to avoid overlapping axes decorations. Can handle complex plot + layouts and colorbars, and is thus recommended. See :doc:`/tutorials/intermediate/constrainedlayout_guide` for examples. @@ -2442,6 +2442,8 @@ def __init__(self, decorations do not overlap. See `.Figure.set_tight_layout` for further details. + - 'none': Do not use a layout engine. + - A `.LayoutEngine` instance. Builtin layout classes are `.ConstrainedLayoutEngine` and `.TightLayoutEngine`, more easily accessible by 'constrained' and 'tight'. Passing an instance diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py index 03236f263f9d..f09090fc7fa7 100644 --- a/lib/matplotlib/pyplot.py +++ b/lib/matplotlib/pyplot.py @@ -740,13 +740,38 @@ def figure(num=None, # autoincrement if None, else integer from 1-N clear : bool, default: False If True and the figure already exists, then it is cleared. - layout : {'constrained', 'tight', 'compressed', \ - `.LayoutEngine`, None}, default: None + layout : {'constrained', 'compressed', 'tight', 'none', `.LayoutEngine`, None}, \ +default: None The layout mechanism for positioning of plot elements to avoid overlapping Axes decorations (labels, ticks, etc). Note that layout - managers can measurably slow down figure display. Defaults to *None* - (but see the documentation of the `.Figure` constructor regarding the - interaction with rcParams). + managers can measurably slow down figure display. + + - '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. + + - 'compressed': uses the same algorithm as 'constrained', but + removes extra space between fixed-aspect-ratio Axes. Best for + simple grids of axes. + + - 'tight': Use the tight layout mechanism. This is a relatively + simple algorithm that adjusts the subplot parameters so that + decorations do not overlap. See `.Figure.set_tight_layout` for + further details. + + - 'none': Do not use a layout engine. + + - A `.LayoutEngine` instance. Builtin layout classes are + `.ConstrainedLayoutEngine` and `.TightLayoutEngine`, more easily + accessible by 'constrained' and 'tight'. Passing an instance + allows third parties to provide their own layout engine. + + If not given, fall back to using the parameters *tight_layout* and + *constrained_layout*, including their config defaults + :rc:`figure.autolayout` and :rc:`figure.constrained_layout.use`. **kwargs Additional keyword arguments are passed to the `.Figure` constructor.