more review suggestions

jklymak · jklymak · commit 94c643b6c25f · 2021-11-18T10:10:25.000+01:00
diff --git a/tutorials/intermediate/arranging_axes.py b/tutorials/intermediate/arranging_axes.py
@@ -1,41 +1,42 @@
 """
-===================================
-Arranging multiple Axes in a Figure
-===================================
+=====================================
+Arranging multiple *Axes* in a Figure
+=====================================
 
-Often more than one "Axes" is wanted on a figure at a time, usually
+Often more than one *Axes* is wanted on a figure at a time, usually
 organized into a regular grid.  Matplotlib has a variety of tools for
-working with grids of Axes that have evolved over the history of the library.
+working with grids of *Axes* that have evolved over the history of the library.
 Here we will discuss the tools we think users should use most often, the tools
-that underpin how Axes are organized, and mention some of the older tools.
+that underpin how *Axes* are organized, and mention some of the older tools.
 
 .. note::
 
-    We use "Axes" to refer to the object that contains plotting
-    artists and the x- and y-Axis.  See `<figure_parts>`_ for more details of
-    Matplotlib terminology.
+    Matplotlib uses *Axes* to refer to an *Artist* that contains plotting
+    *Artists* and the x- and y-*Axis*.  Another term that is often used is
+    "subplot", which refers to an *Axes* that is arranged in a grid.
+    See `<figure_parts>`_ for more details of Matplotlib terminology.
 
 Overview
 ========
 
-Create grid-shaped combinations of Axes
----------------------------------------
+Create grid-shaped combinations of *Axes*
+-----------------------------------------
 
 `~matplotlib.pyplot.subplots`
-    The primary function used to create figures and a grid of Axes.  It
-    creates and places all Axes on the figure at once, and returns an
-    object array with handles for the Axes in the grid.  See
+    The primary function used to create figures and a grid of *Axes*.  It
+    creates and places all *Axes* on the figure at once, and returns an
+    object array with handles for the *Axes* in the grid.  See
     `.Figure.subplots`.
 
 or
 
 `~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
+    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`.
 
-Sometimes it is natural to have more than one distinct group of Axes grids,
+Sometimes it is natural to have more than one distinct group of *Axes* grids,
 in which case Matplotlib has the concept of `~.figure.SubFigure`:
 
 `~matplotlib.figure.SubFigure`
@@ -56,13 +57,14 @@
 `~matplotlib.gridspec.SubplotSpec`
     Specifies the location of the subplot in the given `.GridSpec`.
 
-Adding single Axes at a time
-----------------------------
+Adding single *Axes* at a time
+------------------------------
 
-The above functions create all Axes in a single function call.  It is also
-possible to add Axes one at a time, and this was originally how Matplotlib
+The above functions create all *Axes* in a single function call.  It is also
+possible to add *Axes* one at a time, and this was originally how Matplotlib
 used to work.  Doing so is generally less elegant and flexible, though
-sometimes useful for interactive work or to place an Axes in a custom location:
+sometimes useful for interactive work or to place an *Axes* in a custom
+location:
 
 `~matplotlib.pyplot.subplot` or `.Figure.add_subplot`
     Adds a single subplot on a figure, with 1-based indexing (inherited from
@@ -83,11 +85,11 @@
 # Basic 2x2 grid
 # --------------
 #
-# We can create a basic 2-by-2 grid of Axes using
+# We can create a basic 2-by-2 grid of *Axes* using
 # :func:`~matplotlib.pyplot.subplots`.  It returns a
 # :class:`~matplotlib.figure.Figure` instance and an array of
-# :class:`~matplotlib.axes.Axes` objects.  The Axes objects can
-# be used to access methods to place artists on the Axes; here we
+# :class:`~matplotlib.axes.Axes` objects.  The *Axes* objects can
+# be used to access methods to place artists on the *Axes*; here we
 # use `~.Axes.annotate`, but other examples could be `~.Axes.plot`,
 # `~.Axes.pcolormesh`, etc.
 
@@ -106,7 +108,7 @@
 fig.suptitle('plt.subplots()')
 
 ##############################################################################
-# We will annotate a lot of Axes, so lets encapsulate the annotation, rather
+# We will annotate a lot of *Axes*, so lets encapsulate the annotation, rather
 # than having that large piece of annotation code every time we need it:
 
 
@@ -130,10 +132,10 @@ def annotate_axes(ax, text, fontsize=18):
 fig.suptitle('plt.subplot_mosaic()')
 
 ############################################################################
-# Axes spanning rows or columns in a grid
-# ---------------------------------------
+# *Axes* spanning rows or columns in a grid
+# -----------------------------------------
 #
-# Sometimes we want Axes to span rows or columns of the grid.
+# Sometimes we want *Axes* to span rows or columns of the grid.
 # There are actually multiple ways to accomplish this, but the most
 # convenient is probably to use `~.pyplot.subplot_mosaic` by repeating one
 # of the keys:
@@ -169,13 +171,13 @@ def annotate_axes(ax, text, fontsize=18):
 fig.suptitle('plt.subplot_mosaic()')
 
 ############################################################################
-# Nested Axes layouts
-# -------------------
+# Nested *Axes* layouts
+# ---------------------
 #
-# Sometimes it is helpful to have two or more grids of Axes that
+# Sometimes it is helpful to have two or more grids of *Axes* that
 # may not need to be related to one another.  The most simple way to
 # accomplish this is to use `.Figure.subfigures`.  Note that the alignement
-# of the subfigure layouts is independent with the Axes spines in each
+# of the subfigure layouts is independent with the *Axes* spines in each
 # subfigure having independent positions.  See below for a more verbose
 # way to acheive the same effect with `~.gridspec.GridSpecFromSubplotSpec`.
 
@@ -191,7 +193,7 @@ def annotate_axes(ax, text, fontsize=18):
 subfigs[1].supylabel('ylabel for subfigs[1]')
 
 ############################################################################
-# It is also possible to nest Axes using `~.pyplot.subplot_mosaic` using
+# It is also possible to nest *Axes* using `~.pyplot.subplot_mosaic` using
 # nested lists.  This method does not use subfigures, like above, so lacks
 # the ability to add per-subfigure ``suptitle`` and ``supxlabel``, etc.
 # Rather it is a conveneince wrapper around the `~.SubplotSpec.subgridspec`
@@ -210,14 +212,14 @@ def annotate_axes(ax, text, fontsize=18):
 # Low-level and advanced grid methods
 # ===================================
 #
-# 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
+# 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".
+# specify the location of an *Axes*.
 #
-# The following examples show how to use low-level methods to arrange Axes
-# using GridSpec objects.
+# The following examples show how to use low-level methods to arrange *Axes*
+# using *GridSpec* objects.
 #
 # Basic 2x2 grid
 # --------------
@@ -238,12 +240,12 @@ def annotate_axes(ax, text, fontsize=18):
 fig.suptitle('Manually added subplots using add_gridspec')
 
 ##############################################################################
-# Axes spanning rows or grids in a grid
-# -------------------------------------
+# *Axes* spanning rows or grids in a grid
+# ---------------------------------------
 #
 # 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.  This would be the same
+# 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)
@@ -257,15 +259,15 @@ 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
-# parameters of subplots that are created from the GridSpec.  Note this
+# When a  *GridSpec* is explicitly used, you can adjust the layout
+# parameters of subplots that are created from the  *GridSpec*.  Note this
 # option is not compatible with ``constrained_layout`` or
 # `.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.
+# requires iterations to make the *Axes* tick labels not overlap the *Axes*.
 #
 # These spacing parameters can also be passed to `~.pyplot.subplots` and
 # `~.pyplot.subplot_mosaic` as the *gridspec_kw* argument.
@@ -286,7 +288,7 @@ def annotate_axes(ax, text, fontsize=18):
 # -------------------------------
 #
 # You can create nested layout similar to `~.Figure.subfigures` using
-# `~.gridspec.SubplotSpec.subgridspec`.  Here the Axes spines _are_
+# `~.gridspec.SubplotSpec.subgridspec`.  Here the *Axes* spines _are_
 # aligned.
 #
 # Note this is also available from the more verbose
@@ -313,9 +315,10 @@ def annotate_axes(ax, text, fontsize=18):
 fig.suptitle('nested gridspecs')
 
 ###############################################################################
-# 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.
+# 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)):
