DOC: review changes

jklymak · jklymak · commit f35a501fc98d · 2021-11-17T07:59:32.000+01:00
diff --git a/tutorials/intermediate/arranging_axes.py b/tutorials/intermediate/arranging_axes.py
@@ -210,10 +210,14 @@ def annotate_axes(ax, text, fontsize=18):
 # Low-level and advanced grid methods
 # ===================================
 #
-# `~.pyplot.subplots` and `~.pyplot.subplot_mosaic` provide high-level
-# interfaces to create `~.gridspec.GridSpec` objects and add associated
-# new Axes to a figure at given `~.gridspec.SubplotSpec` inside the
-# *GridSpec*.
+# Internally, the arrangement of a grid of Axes is controlled by creating
+# instances of `~.GridSpec` and `~.SubplotSpec`. GridSpec defines a
+# (possibly non-uniform) grid of cells. Indexing into the GridSpec returns
+# a SubplotSpec that covers one or more grid cells, and can be used to
+# specify the location of an Axes or "subplot".
+#
+# The following examples show how to use low-level methods to arrange Axes
+# using GridSpec objects.
 #
 # Basic 2x2 grid
 # --------------
@@ -239,7 +243,8 @@ def annotate_axes(ax, text, fontsize=18):
 #
 # We can index the *spec* array using `NumPy slice syntax
 # <https://numpy.org/doc/stable/reference/arrays.indexing.html>`_
-# and the new Axes will span the slice:
+# and the new Axes will span the slice.  This would be the same
+# as `fig, axd = plt.subplot_mosaic([['ax0', 'ax0'], ['ax1', 'ax2']], ...)`:
 
 fig = plt.figure(figsize=(4.5, 3.5), constrained_layout=True)
 spec = fig.add_gridspec(2, 2)
@@ -252,7 +257,7 @@ def annotate_axes(ax, text, fontsize=18):
 fig.suptitle('Manually added subplots, spanning a column')
 
 ###############################################################################
-# Manual Adjustments to a Gridspec Layout
+# Manual adjustments to a GridSpec layout
 # ---------------------------------------
 #
 # When a GridSpec is explicitly used, you can adjust the layout
@@ -261,6 +266,9 @@ def annotate_axes(ax, text, fontsize=18):
 # `.Figure.tight_layout` which both ignore *left* and *right* and adjust
 # subplot sizes to fill the figure.  Usually such manual placement
 # requires iterations to make the Axes tick labels not overlap the Axes.
+#
+# These spacing parameters can also be passed to `~.pyplot.subplots` and
+# `~.pyplots.subplot_mosaic` as the *gridspec_kw* argument.
 
 fig = plt.figure(constrained_layout=False, facecolor='0.9')
 gs = fig.add_gridspec(nrows=3, ncols=3, left=0.05, right=0.75,
@@ -275,7 +283,7 @@ def annotate_axes(ax, text, fontsize=18):
 
 ###############################################################################
 # Nested layouts with SubplotSpec
-# ===============================
+# -------------------------------
 #
 # You can create nested layout similar to `~.Figure.subfigures` using
 # `~.gridspec.SubplotSpec.subgridspec`.  Here the Axes spines _are_
@@ -305,9 +313,9 @@ def annotate_axes(ax, text, fontsize=18):
 fig.suptitle('nested gridspecs')
 
 ###############################################################################
-# Here's a more sophisticated example of nested GridSpec where we put
-# a box around each cell of the outer 4x4 grid, by hiding appropriate
-# spines in each of the inner 3x3 grids.
+# Here's a more sophisticated example of nested GridSpec: We create an outer
+# 4x4 grid with each cell containing and inner 3x3 grid of Axes. We outline the
+# outer 4x4 grid by hiding appropriate spines in each of the inner 3x3 grids.
 
 
 def squiggle_xy(a, b, c, d, i=np.arange(0.0, 2*np.pi, 0.05)):
