matplotlib
diff --git a/‎.flake8
-1 b/‎.flake8
-1
diff --git a/‎doc/users/prev_whats_new/whats_new_1.0.rst
+2-1 b/‎doc/users/prev_whats_new/whats_new_1.0.rst
+2-1
diff --git a/‎examples/lines_bars_and_markers/scatter_hist.py
+2-2 b/‎examples/lines_bars_and_markers/scatter_hist.py
+2-2
diff --git a/‎examples/subplots_axes_and_figures/gridspec_and_subplots.py
+4-1 b/‎examples/subplots_axes_and_figures/gridspec_and_subplots.py
+4-1
diff --git a/‎lib/matplotlib/gridspec.py
+4-2 b/‎lib/matplotlib/gridspec.py
+4-2
@@ -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
 
@@ -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
 
@@ -88,8 +88,8 @@ def scatter_hist(x, y, ax, ax_histx, ax_histy):
 # ----------------
 #
 # We may equally define a gridspec with unequal width- and height-ratios to
-# achieve desired layout. Also see the :doc:`/tutorials/intermediate/gridspec`
-# tutorial.
+# achieve desired layout. Also see the
+# :doc:`/tutorials/intermediate/arranging_axes` tutorial.
 
 # start with a square Figure
 fig = plt.figure(figsize=(8, 8))
 
@@ -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
 
@@ -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