Merge pull request matplotlib#20309 from QuLogic/example-kwargs

timhoffm · web-flow · commit 401aa2f7f2c1 · 2021-05-27T00:45:58.000+02:00
DOC: Spell out args/kwargs in examples/tutorials
diff --git a/examples/images_contours_and_fields/contourf_demo.py b/examples/images_contours_and_fields/contourf_demo.py
@@ -41,10 +41,10 @@
 fig1, ax2 = plt.subplots(constrained_layout=True)
 CS = ax2.contourf(X, Y, Z, 10, cmap=plt.cm.bone, origin=origin)
 
-# Note that in the following, we explicitly pass in a subset of
-# the contour levels used for the filled contours.  Alternatively,
-# We could pass in additional levels to provide extra resolution,
-# or leave out the levels kwarg to use all of the original levels.
+# Note that in the following, we explicitly pass in a subset of the contour
+# levels used for the filled contours.  Alternatively, we could pass in
+# additional levels to provide extra resolution, or leave out the *levels*
+# keyword argument to use all of the original levels.
 
 CS2 = ax2.contour(CS, levels=CS.levels[::2], colors='r', origin=origin)
 
diff --git a/examples/images_contours_and_fields/tripcolor_demo.py b/examples/images_contours_and_fields/tripcolor_demo.py
@@ -113,7 +113,7 @@
 # object if the same triangulation was to be used more than once to save
 # duplicated calculations.
 # Can specify one color value per face rather than one per point by using the
-# facecolors kwarg.
+# *facecolors* keyword argument.
 
 fig3, ax3 = plt.subplots()
 ax3.set_aspect('equal')
diff --git a/examples/lines_bars_and_markers/filled_step.py b/examples/lines_bars_and_markers/filled_step.py
@@ -20,8 +20,6 @@ def filled_hist(ax, edges, values, bottoms=None, orientation='v',
     """
     Draw a histogram as a stepped patch.
 
-    Extra kwargs are passed through to `fill_between`
-
     Parameters
     ----------
     ax : Axes
@@ -41,6 +39,9 @@ def filled_hist(ax, edges, values, bottoms=None, orientation='v',
        Orientation of the histogram.  'v' (default) has
        the bars increasing in the positive y-direction.
 
+    **kwargs
+        Extra keyword arguments are passed through to `.fill_between`.
+
     Returns
     -------
     ret : PolyCollection
@@ -103,11 +104,11 @@ def stack_hist(ax, stacked_data, sty_cycle, bottoms=None,
 
         If not given and stacked data is an array defaults to 'default set {n}'
 
-        If stacked_data is a mapping, and labels is None, default to the keys
-        (which may come out in a random order).
+        If *stacked_data* is a mapping, and *labels* is None, default to the
+        keys.
 
-        If stacked_data is a mapping and labels is given then only
-        the columns listed by be plotted.
+        If *stacked_data* is a mapping and *labels* is given then only the
+        columns listed will be plotted.
 
     plot_func : callable, optional
         Function to call to draw the histogram must have signature:
@@ -116,9 +117,9 @@ def stack_hist(ax, stacked_data, sty_cycle, bottoms=None,
                           label=label, **kwargs)
 
     plot_kwargs : dict, optional
-        Any extra kwargs to pass through to the plotting function.  This
-        will be the same for all calls to the plotting function and will
-        over-ride the values in cycle.
+        Any extra keyword arguments to pass through to the plotting function.
+        This will be the same for all calls to the plotting function and will
+        override the values in *sty_cycle*.
 
     Returns
     -------
diff --git a/examples/lines_bars_and_markers/gradient_bar.py b/examples/lines_bars_and_markers/gradient_bar.py
@@ -34,7 +34,7 @@ def gradient_image(ax, extent, direction=0.3, cmap_range=(0, 1), **kwargs):
     extent
         The extent of the image as (xmin, xmax, ymin, ymax).
         By default, this is in Axes coordinates but may be
-        changed using the *transform* kwarg.
+        changed using the *transform* keyword argument.
     direction : float
         The direction of the gradient. This is a number in
         range 0 (=vertical) to 1 (=horizontal).
diff --git a/examples/shapes_and_collections/collections.py b/examples/shapes_and_collections/collections.py
@@ -3,11 +3,10 @@
 Line, Poly and RegularPoly Collection with autoscaling
 =========================================================
 
-For the first two subplots, we will use spirals.  Their
-size will be set in plot units, not data units.  Their positions
-will be set in data units by using the "offsets" and "transOffset"
-kwargs of the `~.collections.LineCollection` and
-`~.collections.PolyCollection`.
+For the first two subplots, we will use spirals.  Their size will be set in
+plot units, not data units.  Their positions will be set in data units by using
+the *offsets* and *transOffset* keyword arguments of the `.LineCollection` and
+`.PolyCollection`.
 
 The third subplot will make regular polygons, with the same
 type of scaling and positioning as in the first two.
@@ -60,7 +59,7 @@
 # but it is good enough to generate a plot that you can use
 # as a starting point.  If you know beforehand the range of
 # x and y that you want to show, it is better to set them
-# explicitly, leave out the autolim kwarg (or set it to False),
+# explicitly, leave out the *autolim* keyword argument (or set it to False),
 # and omit the 'ax1.autoscale_view()' call below.
 
 # Make a transform for the line segments such that their size is
diff --git a/examples/specialty_plots/topographic_hillshading.py b/examples/specialty_plots/topographic_hillshading.py
@@ -13,8 +13,8 @@
 In most cases, hillshading is used purely for visual purposes, and *dx*/*dy*
 can be safely ignored. In that case, you can tweak *vert_exag* (vertical
 exaggeration) by trial and error to give the desired visual effect. However,
-this example demonstrates how to use the *dx* and *dy* kwargs to ensure that
-the *vert_exag* parameter is the true vertical exaggeration.
+this example demonstrates how to use the *dx* and *dy* keyword arguments to
+ensure that the *vert_exag* parameter is the true vertical exaggeration.
 """
 import numpy as np
 import matplotlib.pyplot as plt
diff --git a/examples/statistics/boxplot.py b/examples/statistics/boxplot.py
@@ -3,16 +3,15 @@
 Artist customization in box plots
 =================================
 
-This example demonstrates how to use the various kwargs
-to fully customize box plots. The first figure demonstrates
-how to remove and add individual components (note that the
-mean is the only value not shown by default). The second
-figure demonstrates how the styles of the artists can
-be customized. It also demonstrates how to set the limit
-of the whiskers to specific percentiles (lower right axes)
-
-A good general reference on boxplots and their history can be found
-here: http://vita.had.co.nz/papers/boxplots.pdf
+This example demonstrates how to use the various keyword arguments to fully
+customize box plots. The first figure demonstrates how to remove and add
+individual components (note that the mean is the only value not shown by
+default). The second figure demonstrates how the styles of the artists can be
+customized. It also demonstrates how to set the limit of the whiskers to
+specific percentiles (lower right axes)
+
+A good general reference on boxplots and their history can be found here:
+https://vita.had.co.nz/papers/boxplots.pdf
 
 """
 
diff --git a/examples/statistics/confidence_ellipse.py b/examples/statistics/confidence_ellipse.py
@@ -190,7 +190,7 @@ def get_correlated_dataset(n, dependency, mu, scale):
 # Using the keyword arguments
 # """""""""""""""""""""""""""
 #
-# Use the kwargs specified for matplotlib.patches.Patch in order
+# Use the keyword arguments specified for `matplotlib.patches.Patch` in order
 # to have the ellipse rendered in different ways.
 
 fig, ax_kwargs = plt.subplots(figsize=(6, 6))
@@ -210,7 +210,7 @@ def get_correlated_dataset(n, dependency, mu, scale):
 
 ax_kwargs.scatter(x, y, s=0.5)
 ax_kwargs.scatter(mu[0], mu[1], c='red', s=3)
-ax_kwargs.set_title('Using kwargs')
+ax_kwargs.set_title('Using keyword arguments')
 
 fig.subplots_adjust(hspace=0.25)
 plt.show()
diff --git a/examples/statistics/customized_violin.py b/examples/statistics/customized_violin.py
@@ -3,12 +3,11 @@
 Violin plot customization
 =========================
 
-This example demonstrates how to fully customize violin plots.
-The first plot shows the default style by providing only
-the data. The second plot first limits what matplotlib draws
-with additional kwargs. Then a simplified representation of
-a box plot is drawn on top. Lastly, the styles of the artists
-of the violins are modified.
+This example demonstrates how to fully customize violin plots. The first plot
+shows the default style by providing only the data. The second plot first
+limits what Matplotlib draws with additional keyword arguments. Then a
+simplified representation of a box plot is drawn on top. Lastly, the styles of
+the artists of the violins are modified.
 
 For more information on violin plots, the scikit-learn docs have a great
 section: https://scikit-learn.org/stable/modules/density.html
diff --git a/examples/statistics/errorbars_and_boxes.py b/examples/statistics/errorbars_and_boxes.py
@@ -12,9 +12,9 @@
   1. an `~.axes.Axes` object is passed directly to the function
   2. the function operates on the ``Axes`` methods directly, not through
      the ``pyplot`` interface
-  3. plotting kwargs that could be abbreviated are spelled out for
-     better code readability in the future (for example we use
-     ``facecolor`` instead of ``fc``)
+  3. plotting keyword arguments that could be abbreviated are spelled out for
+     better code readability in the future (for example we use *facecolor*
+     instead of *fc*)
   4. the artists returned by the ``Axes`` plotting methods are then
      returned by the function so that, if desired, their styles
      can be modified later outside of the function (they are not
diff --git a/examples/statistics/hist.py b/examples/statistics/hist.py
@@ -32,7 +32,7 @@
 
 fig, axs = plt.subplots(1, 2, sharey=True, tight_layout=True)
 
-# We can set the number of bins with the `bins` kwarg
+# We can set the number of bins with the *bins* keyword argument.
 axs[0].hist(x, bins=n_bins)
 axs[1].hist(y, bins=n_bins)
 
diff --git a/examples/statistics/histogram_cumulative.py b/examples/statistics/histogram_cumulative.py
@@ -7,14 +7,13 @@
 step function in order to visualize the empirical cumulative
 distribution function (CDF) of a sample. We also show the theoretical CDF.
 
-A couple of other options to the ``hist`` function are demonstrated.
-Namely, we use the ``normed`` parameter to normalize the histogram and
-a couple of different options to the ``cumulative`` parameter.
-The ``normed`` parameter takes a boolean value. When ``True``, the bin
-heights are scaled such that the total area of the histogram is 1. The
-``cumulative`` kwarg is a little more nuanced. Like ``normed``, you
-can pass it True or False, but you can also pass it -1 to reverse the
-distribution.
+A couple of other options to the ``hist`` function are demonstrated. Namely, we
+use the *normed* parameter to normalize the histogram and a couple of different
+options to the *cumulative* parameter. The *normed* parameter takes a boolean
+value. When ``True``, the bin heights are scaled such that the total area of
+the histogram is 1. The *cumulative* keyword argument is a little more nuanced.
+Like *normed*, you can pass it True or False, but you can also pass it -1 to
+reverse the distribution.
 
 Since we're showing a normalized and cumulative histogram, these curves
 are effectively the cumulative distribution functions (CDFs) of the
diff --git a/examples/subplots_axes_and_figures/secondary_axis.py b/examples/subplots_axes_and_figures/secondary_axis.py
@@ -8,7 +8,7 @@
 axes with only one axis visible via `.axes.Axes.secondary_xaxis` and
 `.axes.Axes.secondary_yaxis`.  This secondary axis can have a different scale
 than the main axis by providing both a forward and an inverse conversion
-function in a tuple to the ``functions`` kwarg:
+function in a tuple to the *functions* keyword argument:
 """
 
 import matplotlib.pyplot as plt
@@ -87,9 +87,9 @@ def one_over(x):
 #   nominal plot limits.
 #
 #   In the specific case of the numpy linear interpolation, `numpy.interp`,
-#   this condition can be arbitrarily enforced by providing optional kwargs
-#   *left*, *right* such that values outside the data range are mapped
-#   well outside the plot limits.
+#   this condition can be arbitrarily enforced by providing optional keyword
+#   arguments *left*, *right* such that values outside the data range are
+#   mapped well outside the plot limits.
 
 fig, ax = plt.subplots(constrained_layout=True)
 xdata = np.arange(1, 11, 0.4)
diff --git a/examples/text_labels_and_annotations/annotation_demo.py b/examples/text_labels_and_annotations/annotation_demo.py
@@ -107,7 +107,7 @@
 # In the example below, the *xy* point is in native coordinates (*xycoords*
 # defaults to 'data').  For a polar axes, this is in (theta, radius) space.
 # The text in the example is placed in the fractional figure coordinate system.
-# Text keyword args like horizontal and vertical alignment are respected.
+# Text keyword arguments like horizontal and vertical alignment are respected.
 
 fig, ax = plt.subplots(subplot_kw=dict(projection='polar'), figsize=(3, 3))
 r = np.arange(0, 1, 0.001)
diff --git a/examples/text_labels_and_annotations/fonts_demo.py b/examples/text_labels_and_annotations/fonts_demo.py
@@ -5,7 +5,7 @@
 
 Set font properties using setters.
 
-See :doc:`fonts_demo_kw` to achieve the same effect using kwargs.
+See :doc:`fonts_demo_kw` to achieve the same effect using keyword arguments.
 """
 
 from matplotlib.font_manager import FontProperties
diff --git a/examples/text_labels_and_annotations/fonts_demo_kw.py b/examples/text_labels_and_annotations/fonts_demo_kw.py
@@ -1,9 +1,9 @@
 """
-===================
-Fonts demo (kwargs)
-===================
+==============================
+Fonts demo (keyword arguments)
+==============================
 
-Set font properties using kwargs.
+Set font properties using keyword arguments.
 
 See :doc:`fonts_demo` to achieve the same effect using setters.
 """
diff --git a/examples/text_labels_and_annotations/titles_demo.py b/examples/text_labels_and_annotations/titles_demo.py
@@ -38,8 +38,8 @@
 plt.show()
 
 ###########################################################################
-# Automatic positioning can be turned off by manually specifying the
-# *y* kwarg for the title or setting :rc:`axes.titley` in the rcParams.
+# Automatic positioning can be turned off by manually specifying the *y*
+# keyword argument for the title or setting :rc:`axes.titley` in the rcParams.
 
 fig, axs = plt.subplots(1, 2, constrained_layout=True)
 
diff --git a/examples/ticks_and_spines/custom_ticker1.py b/examples/ticks_and_spines/custom_ticker1.py
@@ -17,7 +17,7 @@
 
 
 def millions(x, pos):
-    """The two args are the value and tick position."""
+    """The two arguments are the value and tick position."""
     return '${:1.1f}M'.format(x*1e-6)
 
 fig, ax = plt.subplots()
diff --git a/examples/ticks_and_spines/date_concise_formatter.py b/examples/ticks_and_spines/date_concise_formatter.py
@@ -101,7 +101,7 @@
 # limits are mostly hours, we label Feb 4 00:00 as simply "Feb-4".
 #
 # Note that these format lists can also be passed to `.ConciseDateFormatter`
-# as optional kwargs.
+# as optional keyword arguments.
 #
 # Here we modify the labels to be "day month year", instead of the ISO
 # "year month day":
@@ -142,8 +142,8 @@
 # Registering a converter with localization
 # =========================================
 #
-# `.ConciseDateFormatter` doesn't have rcParams entries, but localization
-# can be accomplished by passing kwargs to `.ConciseDateConverter` and
+# `.ConciseDateFormatter` doesn't have rcParams entries, but localization can
+# be accomplished by passing keyword arguments to `.ConciseDateConverter` and
 # registering the datatypes you will use with the units registry:
 
 import datetime
diff --git a/examples/units/basic_units.py b/examples/units/basic_units.py
@@ -79,8 +79,8 @@ def __call__(self, *args):
         arg_units = [self.unit]
         for a in args:
             if hasattr(a, 'get_unit') and not hasattr(a, 'convert_to'):
-                # if this arg has a unit type but no conversion ability,
-                # this operation is prohibited
+                # If this argument has a unit type but no conversion ability,
+                # this operation is prohibited.
                 return NotImplemented
 
             if hasattr(a, 'convert_to'):
diff --git a/tutorials/intermediate/constrainedlayout_guide.py b/tutorials/intermediate/constrainedlayout_guide.py
@@ -79,7 +79,8 @@ def example_plot(ax, fontsize=12, hide_labels=False):
 # 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`). However, specifying your figure with the
-# ``constrained_layout=True`` kwarg will do the adjusting automatically.
+# ``constrained_layout=True`` keyword argument will do the adjusting
+# automatically.
 
 fig, ax = plt.subplots(constrained_layout=True)
 example_plot(ax, fontsize=24)
@@ -112,7 +113,7 @@ def example_plot(ax, fontsize=12, hide_labels=False):
 #
 # .. note::
 #
-#   For the `~.axes.Axes.pcolormesh` kwargs (``pc_kwargs``) we use a
+#   For the `~.axes.Axes.pcolormesh` keyword arguments (``pc_kwargs``) we use a
 #   dictionary. Below we will assign one colorbar to a number of axes each
 #   containing a `~.cm.ScalarMappable`; specifying the norm and colormap
 #   ensures the colorbar is accurate for all the axes.
diff --git a/tutorials/intermediate/imshow_extent.py b/tutorials/intermediate/imshow_extent.py
@@ -2,18 +2,18 @@
 *origin* and *extent* in `~.Axes.imshow`
 ========================================
 
-:meth:`~.Axes.imshow` allows you to render an image (either a 2D array
-which will be color-mapped (based on *norm* and *cmap*) or a 3D RGB(A)
-array which will be used as-is) to a rectangular region in data space.
-The orientation of the image in the final rendering is controlled by
-the *origin* and *extent* kwargs (and attributes on the resulting
-`.AxesImage` instance) and the data limits of the axes.
-
-The *extent* kwarg controls the bounding box in data coordinates that
-the image will fill specified as ``(left, right, bottom, top)`` in
-**data coordinates**, the *origin* kwarg controls how the image fills
-that bounding box, and the orientation in the final rendered image is
-also affected by the axes limits.
+:meth:`~.Axes.imshow` allows you to render an image (either a 2D array which
+will be color-mapped (based on *norm* and *cmap*) or a 3D RGB(A) array which
+will be used as-is) to a rectangular region in data space.  The orientation of
+the image in the final rendering is controlled by the *origin* and *extent*
+keyword arguments (and attributes on the resulting `.AxesImage` instance) and
+the data limits of the axes.
+
+The *extent* keyword arguments controls the bounding box in data coordinates
+that the image will fill specified as ``(left, right, bottom, top)`` in **data
+coordinates**, the *origin* keyword argument controls how the image fills that
+bounding box, and the orientation in the final rendered image is also affected
+by the axes limits.
 
 .. hint:: Most of the code below is used for adding labels and informative
    text to the plots. The described effects of *origin* and *extent* can be
diff --git a/tutorials/introductory/lifecycle.py b/tutorials/introductory/lifecycle.py
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/text_intro.py b/tutorials/text/text_intro.py
diff --git a/tutorials/text/text_props.py b/tutorials/text/text_props.py
