@@ -210,10 +210,14 @@ def annotate_axes(ax, text, fontsize=18):
210210# Low-level and advanced grid methods
211211# ===================================
212212#
213- # `~.pyplot.subplots` and `~.pyplot.subplot_mosaic` provide high-level
214- # interfaces to create `~.gridspec.GridSpec` objects and add associated
215- # new Axes to a figure at given `~.gridspec.SubplotSpec` inside the
216- # *GridSpec*.
213+ # Internally, the arrangement of a grid of Axes is controlled by creating
214+ # instances of `~.GridSpec` and `~.SubplotSpec`. GridSpec defines a
215+ # (possibly non-uniform) grid of cells. Indexing into the GridSpec returns
216+ # a SubplotSpec that covers one or more grid cells, and can be used to
217+ # specify the location of an Axes or "subplot".
218+ #
219+ # The following examples show how to use low-level methods to arrange Axes
220+ # using GridSpec objects.
217221#
218222# Basic 2x2 grid
219223# --------------
@@ -239,7 +243,8 @@ def annotate_axes(ax, text, fontsize=18):
239243#
240244# We can index the *spec* array using `NumPy slice syntax
241245# <https://numpy.org/doc/stable/reference/arrays.indexing.html>`_
242- # and the new Axes will span the slice:
246+ # and the new Axes will span the slice. This would be the same
247+ # as `fig, axd = plt.subplot_mosaic([['ax0', 'ax0'], ['ax1', 'ax2']], ...)`:
243248
244249fig = plt .figure (figsize = (4.5 ,3.5 ),constrained_layout = True )
245250spec = fig .add_gridspec (2 ,2 )
@@ -252,7 +257,7 @@ def annotate_axes(ax, text, fontsize=18):
252257fig .suptitle ('Manually added subplots, spanning a column' )
253258
254259###############################################################################
255- # ManualAdjustments to aGridspec Layout
260+ # Manualadjustments to aGridSpec layout
256261# ---------------------------------------
257262#
258263# When a GridSpec is explicitly used, you can adjust the layout
@@ -261,6 +266,9 @@ def annotate_axes(ax, text, fontsize=18):
261266# `.Figure.tight_layout` which both ignore *left* and *right* and adjust
262267# subplot sizes to fill the figure. Usually such manual placement
263268# requires iterations to make the Axes tick labels not overlap the Axes.
269+ #
270+ # These spacing parameters can also be passed to `~.pyplot.subplots` and
271+ # `~.pyplots.subplot_mosaic` as the *gridspec_kw* argument.
264272
265273fig = plt .figure (constrained_layout = False ,facecolor = '0.9' )
266274gs = fig .add_gridspec (nrows = 3 ,ncols = 3 ,left = 0.05 ,right = 0.75 ,
@@ -275,7 +283,7 @@ def annotate_axes(ax, text, fontsize=18):
275283
276284###############################################################################
277285# Nested layouts with SubplotSpec
278- #===============================
286+ #-------------------------------
279287#
280288# You can create nested layout similar to `~.Figure.subfigures` using
281289# `~.gridspec.SubplotSpec.subgridspec`. Here the Axes spines _are_
@@ -305,9 +313,9 @@ def annotate_axes(ax, text, fontsize=18):
305313fig .suptitle ('nested gridspecs' )
306314
307315###############################################################################
308- # Here's a more sophisticated example of nested GridSpec where we put
309- #a box around each cellof the outer 4x4 grid, by hiding appropriate
310- # spines in each of the inner 3x3 grids.
316+ # Here's a more sophisticated example of nested GridSpec: We create an outer
317+ #4x4 grid with each cellcontaining and inner 3x3 grid of Axes. We outline the
318+ #outer 4x4 grid by hiding appropriate spines in each of the inner 3x3 grids.
311319
312320
313321def squiggle_xy (a ,b ,c ,d ,i = np .arange (0.0 ,2 * np .pi ,0.05 )):