From bfddd078cdf4a7e68ba30b20bda11530c3803f23 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Wed, 4 Jan 2023 20:10:51 -0500 Subject: [PATCH 1/4] DOC: mark mosaic as no longer provisional --- doc/users/prev_whats_new/whats_new_3.3.0.rst | 2 +- .../subplots_axes_and_figures}/mosaic.py | 8 ++------ lib/matplotlib/figure.py | 7 +------ lib/matplotlib/pyplot.py | 2 +- tutorials/intermediate/arranging_axes.py | 10 ++++++---- tutorials/introductory/quick_start.py | 2 +- 6 files changed, 12 insertions(+), 19 deletions(-) rename {tutorials/provisional => examples/subplots_axes_and_figures}/mosaic.py (98%) diff --git a/doc/users/prev_whats_new/whats_new_3.3.0.rst b/doc/users/prev_whats_new/whats_new_3.3.0.rst index f53f94b038bd..58959627246a 100644 --- a/doc/users/prev_whats_new/whats_new_3.3.0.rst +++ b/doc/users/prev_whats_new/whats_new_3.3.0.rst @@ -50,7 +50,7 @@ or as a string (with single-character Axes labels): ha='center', va='center', fontsize=36, color='darkgrey') -See :doc:`/tutorials/provisional/mosaic` for more details and examples. +See :doc:`/gallery/subplots_axes_and_figures/mosaic` for more details and examples. ``GridSpec.subplots()`` ----------------------- diff --git a/tutorials/provisional/mosaic.py b/examples/subplots_axes_and_figures/mosaic.py similarity index 98% rename from tutorials/provisional/mosaic.py rename to examples/subplots_axes_and_figures/mosaic.py index ac56d5f9f5d7..302c85c3accf 100644 --- a/tutorials/provisional/mosaic.py +++ b/examples/subplots_axes_and_figures/mosaic.py @@ -1,14 +1,10 @@ """ +.. redirect-from:: /gallery/subplots_axes_and_figures/mosaic + ======================================= Complex and semantic figure composition ======================================= -.. warning:: - - This tutorial documents experimental / provisional API. - We are releasing this in v3.3 to get user feedback. We may - make breaking changes in future versions with no warning. - Laying out Axes in a Figure in a non-uniform grid can be both tedious and verbose. For dense, even grids we have `.Figure.subplots` but for diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index b006ca467be1..8215c7105e51 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -1797,12 +1797,7 @@ def subplot_mosaic(self, mosaic, *, sharex=False, sharey=False, This is a helper function to build complex GridSpec layouts visually. - .. note:: - - This API is provisional and may be revised in the future based on - early user feedback. - - See :doc:`/tutorials/provisional/mosaic` + See :doc:`/gallery/subplots_axes_and_figures/mosaic` for an example and full API documentation Parameters diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py index 4e9734e184dc..5fe2fbf57274 100644 --- a/lib/matplotlib/pyplot.py +++ b/lib/matplotlib/pyplot.py @@ -1504,7 +1504,7 @@ def subplot_mosaic(mosaic, *, sharex=False, sharey=False, This API is provisional and may be revised in the future based on early user feedback. - See :doc:`/tutorials/provisional/mosaic` + See :doc:`/gallery/subplots_axes_and_figures/mosaic` for an example and full API documentation Parameters diff --git a/tutorials/intermediate/arranging_axes.py b/tutorials/intermediate/arranging_axes.py index 519890d14ce8..3fbfb7b6e239 100644 --- a/tutorials/intermediate/arranging_axes.py +++ b/tutorials/intermediate/arranging_axes.py @@ -32,9 +32,10 @@ `~matplotlib.pyplot.subplot_mosaic` A simple way to create figures and a grid of Axes, with the added - flexibility that Axes can also span rows or columns. The Axes - are returned in a labelled dictionary instead of an array. See also - `.Figure.subplot_mosaic` and :doc:`/tutorials/provisional/mosaic`. + flexibility that Axes can also span rows or columns. The Axes are returned + in a labelled dictionary instead of an array. See also + `.Figure.subplot_mosaic` and + :doc:`/gallery/subplots_axes_and_figures/mosaic`. Sometimes it is natural to have more than one distinct group of Axes grids, in which case Matplotlib has the concept of `.SubFigure`: @@ -393,7 +394,8 @@ def squiggle_xy(a, b, c, d, i=np.arange(0.0, 2*np.pi, 0.05)): # More reading # ============ # -# - More details about :doc:`subplot mosaic `. +# - More details about :doc:`subplot mosaic +# `. # - More details about :doc:`constrained layout # `, used to align # spacing in most of these examples. diff --git a/tutorials/introductory/quick_start.py b/tutorials/introductory/quick_start.py index 9ecddcf2af4f..2caacc5aee22 100644 --- a/tutorials/introductory/quick_start.py +++ b/tutorials/introductory/quick_start.py @@ -566,7 +566,7 @@ def my_plotter(ax, data1, data2, param_dict): ############################################################################### # Matplotlib has quite sophisticated tools for arranging Axes: See # :doc:`/tutorials/intermediate/arranging_axes` and -# :doc:`/tutorials/provisional/mosaic`. +# :doc:`/gallery/subplots_axes_and_figures/mosaic`. # # # More reading From b4b415007e0a33fb0e6efddc148ad88ed28123ee Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Thu, 5 Jan 2023 19:30:13 -0500 Subject: [PATCH 2/4] DOC: correct redirect Co-authored-by: Jody Klymak --- examples/subplots_axes_and_figures/mosaic.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/subplots_axes_and_figures/mosaic.py b/examples/subplots_axes_and_figures/mosaic.py index 302c85c3accf..c4801ddb66c0 100644 --- a/examples/subplots_axes_and_figures/mosaic.py +++ b/examples/subplots_axes_and_figures/mosaic.py @@ -1,5 +1,5 @@ """ -.. redirect-from:: /gallery/subplots_axes_and_figures/mosaic +.. redirect-from:: /tutorials/provisional/mosaic ======================================= Complex and semantic figure composition From 4f7a65eaa8ae1192fce54ed7688be722eea3d65b Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Fri, 6 Jan 2023 11:11:27 -0500 Subject: [PATCH 3/4] DOC: make sure mosaic is in the title for ctrl-f searching --- examples/subplots_axes_and_figures/mosaic.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/examples/subplots_axes_and_figures/mosaic.py b/examples/subplots_axes_and_figures/mosaic.py index c4801ddb66c0..9b77893bb2d6 100644 --- a/examples/subplots_axes_and_figures/mosaic.py +++ b/examples/subplots_axes_and_figures/mosaic.py @@ -1,11 +1,12 @@ """ .. redirect-from:: /tutorials/provisional/mosaic -======================================= -Complex and semantic figure composition -======================================= +======================================================== +Complex and semantic figure composition (subplot_mosaic) +======================================================== + Laying out Axes in a Figure in a non-uniform grid can be both tedious and verbose. For dense, even grids we have `.Figure.subplots` but for more complex layouts, such as Axes that span multiple columns / rows From 0bc10e9a550bbdaddd9b7b23d84732efdb5f6d82 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Fri, 6 Jan 2023 15:26:34 -0500 Subject: [PATCH 4/4] DOC: add note that subplot_mosaic now stable API --- doc/users/next_whats_new/per_subplot_mosaic.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/doc/users/next_whats_new/per_subplot_mosaic.rst b/doc/users/next_whats_new/per_subplot_mosaic.rst index bb48bd5e281d..f62e231d2665 100644 --- a/doc/users/next_whats_new/per_subplot_mosaic.rst +++ b/doc/users/next_whats_new/per_subplot_mosaic.rst @@ -1,3 +1,11 @@ +``subplot_mosaic`` no longer provisional +---------------------------------------- + +The API on `.Figure.subplot_mosaic` and `.pyplot.subplot_mosaic` are now +considered stable and will change under Matplotlib's normal deprecation +process. + + Per-subplot keyword arguments in ``subplot_mosaic`` ----------------------------------------------------