(Mostly) avoid the term "command" in the docs.

anntzer · anntzer · commit 0d4f2d539962 · 2020-01-08T19:33:26.000+01:00
It's a MATLABism; Python has functions and methods.  There are some
places where "command" does read fine, though.
diff --git a/examples/images_contours_and_fields/contourf_demo.py b/examples/images_contours_and_fields/contourf_demo.py
@@ -81,7 +81,7 @@
 ax2.set_title('Listed colors (3 masked regions)')
 ax2.clabel(CS4, fmt='%2.1f', colors='w', fontsize=14)
 
-# Notice that the colorbar command gets all the information it
+# Notice that the colorbar gets all the information it
 # needs from the ContourSet object, CS3.
 fig2.colorbar(CS3)
 
diff --git a/examples/misc/transoffset.py b/examples/misc/transoffset.py
@@ -1,19 +1,19 @@
 """
-===========
-Transoffset
-===========
+======================
+transforms.offset_copy
+======================
 
-This illustrates the use of transforms.offset_copy to
+This illustrates the use of `.transforms.offset_copy` to
 make a transform that positions a drawing element such as
 a text string at a specified offset in screen coordinates
 (dots or inches) relative to a location given in any
 coordinates.
 
 Every Artist (Text, Line2D, etc.) has a transform that can be
 set when the Artist is created, such as by the corresponding
-pyplot command.  By default this is usually the Axes.transData
-transform, going from data units to screen dots.  We can
-use the offset_copy function to make a modified copy of
+pyplot function.  By default this is usually the Axes.transData
+transform, going from data units to screen pixels.  We can
+use the `.offset_copy` function to make a modified copy of
 this transform, where the modification consists of an
 offset.
 """
@@ -32,7 +32,7 @@
 # If we want the same offset for each text instance,
 # we only need to make one transform.  To get the
 # transform argument to offset_copy, we need to make the axes
-# first; the subplot command above is one way to do this.
+# first; the subplot function above is one way to do this.
 trans_offset = mtransforms.offset_copy(ax.transData, fig=fig,
                                        x=0.05, y=0.10, units='inches')
 
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -17,21 +17,17 @@
 
 at the ipython shell prompt.
 
-For the most part, direct use of the object-oriented library is
-encouraged when programming; pyplot is primarily for working
-interactively.  The
-exceptions are the pyplot commands :func:`~matplotlib.pyplot.figure`,
-:func:`~matplotlib.pyplot.subplot`,
-:func:`~matplotlib.pyplot.subplots`, and
-:func:`~pyplot.savefig`, which can greatly simplify scripting.
+For the most part, direct use of the object-oriented library is encouraged when
+programming; pyplot is primarily for working interactively.  The exceptions are
+the pyplot functions `.pyplot.figure`, `.pyplot.subplot`, `.pyplot.subplots`,
+and `.pyplot.savefig`, which can greatly simplify scripting.
 
 Modules include:
 
     :mod:`matplotlib.axes`
-        defines the :class:`~matplotlib.axes.Axes` class.  Most pyplot
-        commands are wrappers for :class:`~matplotlib.axes.Axes`
-        methods.  The axes module is the highest level of OO access to
-        the library.
+        defines the `~matplotlib.axes.Axes` class.  Most pyplot functions are
+        wrappers for `~matplotlib.axes.Axes` methods.  The axes module is the
+        highest level of OO access to the library.
 
     :mod:`matplotlib.figure`
         defines the :class:`~matplotlib.figure.Figure` class.
@@ -923,7 +919,7 @@ def rc(group, **kwargs):
     'aa'    'antialiased'
     =====   =================
 
-    Thus you could abbreviate the above rc command as::
+    Thus you could abbreviate the above call as::
 
           rc('lines', lw=2, c='r')
 
diff --git a/lib/matplotlib/animation.py b/lib/matplotlib/animation.py
@@ -230,7 +230,7 @@ def grab_frame(self, **savefig_kwargs):
         Grab the image information from the figure and save as a movie frame.
 
         All keyword arguments in *savefig_kwargs* are passed on to the
-        `~.Figure.savefig` command that saves the figure.
+        `~.Figure.savefig` call that saves the figure.
         """
 
     @abc.abstractmethod
@@ -1020,8 +1020,7 @@ class to use, such as 'ffmpeg'. If ``None``, defaults to
            between the frames from the different animations.
 
         savefig_kwargs : dict, optional
-           Is a dictionary containing keyword arguments to be passed
-           on to the `~.Figure.savefig` command which is called repeatedly to
+           Keyword arguments passed to each `~.Figure.savefig` call used to
            save the individual frames.
 
         progress_callback : function, optional
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -352,7 +352,7 @@ def legend(self, *args, **kwargs):
 
         Notes
         -----
-        Not all kinds of artist are supported by the legend command. See
+        Some artists are not supported by this function.  See
         :doc:`/tutorials/intermediate/legend_guide` for details.
 
         Examples
@@ -927,13 +927,11 @@ def axhspan(self, ymin, ymax, xmin=0, xmax=1, **kwargs):
         """
         Add a horizontal span (rectangle) across the axis.
 
-        Draw a horizontal span (rectangle) from *ymin* to *ymax*.
-        With the default values of *xmin* = 0 and *xmax* = 1, this
-        always spans the xrange, regardless of the xlim settings, even
-        if you change them, e.g., with the :meth:`set_xlim` command.
-        That is, the horizontal extent is in axes coords: 0=left,
-        0.5=middle, 1.0=right but the *y* location is in data
-        coordinates.
+        The rectangle spans from *ymin* to *ymax* vertically, and, by default,
+        the whole x-axis horizontally.  The x-span can be set using *xmin*
+        (default: 0) and *xmax* (default: 1) which are in axis units; e.g.
+        ``xmin = 0.5`` always refers to the middle of the x-axis regardless of
+        the limits set by `~.Axes.set_xlim`.
 
         Parameters
         ----------
@@ -981,12 +979,11 @@ def axvspan(self, xmin, xmax, ymin=0, ymax=1, **kwargs):
         """
         Add a vertical span (rectangle) across the axes.
 
-        Draw a vertical span (rectangle) from *xmin* to *xmax*.  With
-        the default values of *ymin* = 0 and *ymax* = 1. This always
-        spans the yrange, regardless of the ylim settings, even if you
-        change them, e.g., with the :meth:`set_ylim` command.  That is,
-        the vertical extent is in axes coords: 0=bottom, 0.5=middle,
-        1.0=top but the x location is in data coordinates.
+        The rectangle spans from *xmin* to *xmax* horizontally, and, by
+        default, the whole y-axis vertically.  The y-span can be set using
+        *ymin* (default: 0) and *ymax* (default: 1) which are in axis units;
+        e.g. ``ymin = 0.5`` always refers to the middle of the y-axis
+        regardless of the limits set by `~.Axes.set_ylim`.
 
         Parameters
         ----------
@@ -1535,7 +1532,7 @@ def plot(self, *args, scalex=True, scaley=True, data=None, **kwargs):
             >>> plot([1, 2, 3], [1, 2, 3], 'go-', label='line 1', linewidth=2)
             >>> plot([1, 2, 3], [1, 4, 9], 'rs', label='line 2')
 
-            If you make multiple lines with one plot command, the kwargs
+            If you make multiple lines with one plot call, the kwargs
             apply to all those lines.
 
             Here is a list of available `.Line2D` properties:
@@ -3119,9 +3116,9 @@ def errorbar(self, x, y, yerr=None, xerr=None,
         Other Parameters
         ----------------
         **kwargs
-            All other keyword arguments are passed on to the plot
-            command for the markers. For example, this code makes big red
-            squares with thick green edges::
+            All other keyword arguments are passed on to the `~.Axes.plot` call
+            drawing the markers. For example, this code makes big red squares
+            with thick green edges::
 
                 x, y, yerr = rand(3, 10)
                 errorbar(x, y, yerr, marker='s', mfc='red',
@@ -6455,7 +6452,7 @@ def hist(self, x, bins=None, range=None, density=False, weights=None,
         label : str or None, optional, default: None
             String, or sequence of strings to match multiple datasets.  Bar
             charts yield multiple patches per dataset, but only the first gets
-            the label, so that the legend command will work as expected.
+            the label, so that `~.Axes.legend` will work as expected.
 
         stacked : bool, optional, default:False
             If ``True``, multiple data are stacked on top of each other If
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -116,8 +116,7 @@ def _process_plot_format(fmt):
 
 class _process_plot_var_args:
     """
-    Process variable length arguments to the plot command, so that
-    plot commands like the following are supported::
+    Process variable length arguments to `~.Axes.plot`, to support ::
 
       plot(t, s)
       plot(t1, s1, t2, s2)
diff --git a/lib/matplotlib/backends/backend_mixed.py b/lib/matplotlib/backends/backend_mixed.py
@@ -76,21 +76,14 @@ def __getattr__(self, attr):
     def start_rasterizing(self):
         """
         Enter "raster" mode.  All subsequent drawing commands (until
-        stop_rasterizing is called) will be drawn with the raster
-        backend.
-
-        If start_rasterizing is called multiple times before
-        stop_rasterizing is called, this method has no effect.
+        `stop_rasterizing` is called) will be drawn with the raster backend.
         """
-
         # change the dpi of the figure temporarily.
         self.figure.set_dpi(self.dpi)
-
         if self._bbox_inches_restore:  # when tight bbox is used
             r = process_figure_for_rasterizing(self.figure,
                                                self._bbox_inches_restore)
             self._bbox_inches_restore = r
-
         if self._rasterizing == 0:
             self._raster_renderer = self._raster_renderer_class(
                 self._width*self.dpi, self._height*self.dpi, self.dpi)
@@ -100,11 +93,12 @@ def start_rasterizing(self):
     def stop_rasterizing(self):
         """
         Exit "raster" mode.  All of the drawing that was done since
-        the last start_rasterizing command will be copied to the
+        the last `start_rasterizing` call will be copied to the
         vector backend by calling draw_image.
 
-        If stop_rasterizing is called multiple times before
-        start_rasterizing is called, this method has no effect.
+        If `start_rasterizing` has been called multiple times,
+        `stop_rasterizing` must be called the same number of times before
+        "raster" mode is exited.
         """
         self._rasterizing -= 1
         if self._rasterizing == 0:
diff --git a/lib/matplotlib/backends/backend_pgf.py b/lib/matplotlib/backends/backend_pgf.py
@@ -275,8 +275,9 @@ def __init__(self):
                 encoding="utf-8", cwd=self.tmpdir)
         except FileNotFoundError:
             raise RuntimeError(
-                "Latex command not found. Install %r or change "
-                "pgf.texsystem to the desired command." % self.texcommand)
+                f"{self.texcommand} not found.  Install it or change "
+                f"rcParams['pgf.texsystem'] to an available TeX "
+                f"implementation.")
         except OSError:
             raise RuntimeError("Error starting process %r" % self.texcommand)
         test_input = self.latex_header + latex_end
@@ -856,7 +857,7 @@ def _print_pgf_to_fh(self, fh, *args,
 
     def print_pgf(self, fname_or_fh, *args, **kwargs):
         """
-        Output pgf commands for drawing the figure so it can be included and
+        Output pgf macros for drawing the figure so it can be included and
         rendered in latex documents.
         """
         if kwargs.get("dryrun", False):
diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
@@ -1791,7 +1791,7 @@ def legend(self, *args, **kwargs):
 
         Notes
         -----
-        Not all kinds of artist are supported by the legend command. See
+        Some artists are not supported by this function.  See
         :doc:`/tutorials/intermediate/legend_guide` for details.
         """
 
diff --git a/lib/matplotlib/tests/test_figure.py b/lib/matplotlib/tests/test_figure.py
@@ -17,7 +17,6 @@
 @image_comparison(['figure_align_labels'],
                   tol={'aarch64': 0.02}.get(platform.machine(), 0.0))
 def test_align_labels():
-    # Check the figure.align_labels() command
     fig = plt.figure(tight_layout=True)
     gs = gridspec.GridSpec(3, 3)
 
diff --git a/lib/matplotlib/tight_bbox.py b/lib/matplotlib/tight_bbox.py
@@ -1,5 +1,5 @@
 """
-This module is to support *bbox_inches* option in savefig command.
+This module is to support the *bbox_inches* parameter in `.Figure.savefig`.
 """
 
 from matplotlib.transforms import Bbox, TransformedBbox, Affine2D
diff --git a/lib/mpl_toolkits/axisartist/axislines.py b/lib/mpl_toolkits/axisartist/axislines.py
@@ -1,13 +1,13 @@
 """
 Axislines includes modified implementation of the Axes class. The
 biggest difference is that the artists responsible for drawing the axis spine,
-ticks, ticklabels and axis labels are separated out from mpl's Axis
+ticks, ticklabels and axis labels are separated out from Matplotlib's Axis
 class. Originally, this change was motivated to support curvilinear
 grid. Here are a few reasons that I came up with a new axes class:
 
 * "top" and "bottom" x-axis (or "left" and "right" y-axis) can have
   different ticks (tick locations and labels). This is not possible
-  with the current mpl, although some twin axes trick can help.
+  with the current Matplotlib, although some twin axes trick can help.
 
 * Curvilinear grid.
 
@@ -29,11 +29,10 @@
 * offsetText
 * label
 
-Note that these are separate artists from Axis class of the
-original mpl, thus most of tick-related command in the original mpl
-won't work, although some effort has made to work with. For example,
-color and markerwidth of the ax.axis["bottom"].major_ticks will follow
-those of Axes.xaxis unless explicitly specified.
+Note that these are separate artists from `matplotlib.axis.Axis`, thus most
+tick-related functions in Matplotlib won't work. For example, color and
+markerwidth of the ``ax.axis["bottom"].major_ticks`` will follow those of
+Axes.xaxis unless explicitly specified.
 
 In addition to AxisArtist, the Axes will have *gridlines* attribute,
 which obviously draws grid lines. The gridlines needs to be separated
diff --git a/tutorials/intermediate/constrainedlayout_guide.py b/tutorials/intermediate/constrainedlayout_guide.py
@@ -105,8 +105,8 @@ def example_plot(ax, fontsize=12, nodec=False):
 # Colorbars
 # =========
 #
-# If you create a colorbar with the :func:`~matplotlib.pyplot.colorbar`
-# command you need to make room for it.  ``constrained_layout`` does this
+# If you create a colorbar with `.Figure.colorbar`,
+# you need to make room for it.  ``constrained_layout`` does this
 # automatically.  Note that if you specify ``use_gridspec=True`` it will be
 # ignored because this option is made for improving the layout via
 # ``tight_layout``.
@@ -498,17 +498,16 @@ def docomplicated(suptitle=None):
 #
 #
 # Limitations
-# ========================
+# ===========
 #
 # Incompatible functions
 # ----------------------
 #
-# ``constrained_layout`` will not work on subplots
-# created via the `.pyplot.subplot` command.  The reason is that each of these
-# commands creates a separate `.GridSpec` instance and ``constrained_layout``
-# uses (nested) gridspecs to carry out the layout.  So the following fails
-# to yield a nice layout:
-
+# ``constrained_layout`` will not work on subplots created via
+# `.pyplot.subplot`.  The reason is that each call to `.pyplot.subplot` creates
+# a separate `.GridSpec` instance and ``constrained_layout`` uses (nested)
+# gridspecs to carry out the layout.  So the following fails to yield a nice
+# layout:
 
 fig = plt.figure()
 
diff --git a/tutorials/intermediate/tight_layout_guide.py b/tutorials/intermediate/tight_layout_guide.py
@@ -47,9 +47,8 @@ def example_plot(ax, fontsize=12):
 ###############################################################################
 # To prevent this, the location of axes needs to be adjusted. For
 # subplots, this can be done by adjusting the subplot params
-# (:ref:`howto-subplots-adjust`). Matplotlib v1.1 introduces a new
-# command :func:`~matplotlib.pyplot.tight_layout` that does this
-# automatically for you.
+# (:ref:`howto-subplots-adjust`). Matplotlib v1.1 introduced
+# `.Figure.tight_layout` that does this automatically for you.
 
 fig, ax = plt.subplots()
 example_plot(ax, fontsize=24)
@@ -336,10 +335,9 @@ def example_plot(ax, fontsize=12):
 # Colorbar
 # ========
 #
-# If you create a colorbar with the :func:`~matplotlib.pyplot.colorbar`
-# command, the created colorbar is an instance of Axes, *not* Subplot, so
-# tight_layout does not work. With Matplotlib v1.1, you may create a
-# colorbar as a subplot using the gridspec.
+# If you create a colorbar with `.Figure.colorbar`, the created colorbar is
+# an instance of Axes, *not* Subplot, so tight_layout does not work. With
+# Matplotlib v1.1, you may create a colorbar as a subplot using the gridspec.
 
 plt.close('all')
 arr = np.arange(100).reshape((10, 10))
diff --git a/tutorials/introductory/customizing.py b/tutorials/introductory/customizing.py
@@ -112,14 +112,14 @@
 
 ###############################################################################
 # Matplotlib also provides a couple of convenience functions for modifying rc
-# settings. The :func:`matplotlib.rc` command can be used to modify multiple
+# settings. `matplotlib.rc` can be used to modify multiple
 # settings in a single group at once, using keyword arguments:
 
 mpl.rc('lines', linewidth=4, color='g')
 plt.plot(data)
 
 ###############################################################################
-# The :func:`matplotlib.rcdefaults` command will restore the standard matplotlib
+# `matplotlib.rcdefaults` will restore the standard matplotlib
 # default settings.
 #
 # There is some degree of validation when setting the values of rcParams, see
diff --git a/tutorials/introductory/pyplot.py b/tutorials/introductory/pyplot.py
diff --git a/tutorials/introductory/usage.py b/tutorials/introductory/usage.py
diff --git a/tutorials/text/annotations.py b/tutorials/text/annotations.py
diff --git a/tutorials/text/text_props.py b/tutorials/text/text_props.py
