DOC: modernize gridspec tutorial

Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>

Author: 3 people

.flake8

@@ -94,7 +94,6 @@ per-file-ignores =
     tutorials/colors/colormap-manipulation.py: E402
     tutorials/intermediate/artists.py: E402
     tutorials/intermediate/constrainedlayout_guide.py: E402
-    tutorials/intermediate/gridspec.py: E402
     tutorials/intermediate/legend_guide.py: E402
     tutorials/intermediate/tight_layout_guide.py: E402
     tutorials/introductory/customizing.py: E501

doc/users/prev_whats_new/whats_new_1.0.rst

@@ -23,7 +23,8 @@ Sophisticated subplot grid layout
 
 Jae-Joon Lee has written :mod:`~matplotlib.gridspec`, a new module for
 doing complex subplot layouts, featuring row and column spans and
-more.  See :doc:`/tutorials/intermediate/gridspec` for a tutorial overview.
+more.  See :doc:`/tutorials/intermediate/arranging_axes` for a tutorial
+overview.
 
 .. figure:: ../../gallery/userdemo/images/sphx_glr_demo_gridspec01_001.png
    :target: ../../gallery/userdemo/demo_gridspec01.html

examples/lines_bars_and_markers/scatter_hist.py

@@ -60,7 +60,7 @@ def scatter_hist(x, y, ax, ax_histx, ax_histy):
 # --------------------------------------------
 #
 # We define a gridspec with unequal width- and height-ratios to achieve desired
-# layout.  Also see the :doc:`/tutorials/intermediate/gridspec` tutorial.
+# layout.  Also see the :doc:`/tutorials/intermediate/arranging_axes` tutorial.
 
 # Start with a square Figure.
 fig = plt.figure(figsize=(6, 6))

examples/subplots_axes_and_figures/gridspec_and_subplots.py

@@ -8,7 +8,10 @@
 and then remove the covered axes and fill the gap with a new bigger axes.
 Here we create a layout with the bottom two axes in the last column combined.
 
-See also :doc:`/tutorials/intermediate/gridspec`.
+To start with this layout (rather than removing the overlapping axes) use
+`~.pyplot.subplot_mosaic`.
+
+See also :doc:`/tutorials/intermediate/arranging_axes`.
 """
 
 import matplotlib.pyplot as plt

lib/matplotlib/gridspec.py

@@ -5,8 +5,10 @@
 The `GridSpec` specifies the overall grid structure. Individual cells within
 the grid are referenced by `SubplotSpec`\s.
 
-See the tutorial :doc:`/tutorials/intermediate/gridspec` for a comprehensive
-usage guide.
+Often, users need not access this module directly, and can use higher-level
+methods like `~.pyplot.subplots`, `~.pyplot.subplot_mosaic` and
+`~.Figure.subfigures`. See the tutorial
+:doc:`/tutorials/intermediate/arranging_axes` for a guide.
 """
 
 import copy