Merge pull request #14680 from timhoffm/parameter-formatting

tacaswell · web-flow · commit 0d486c2fadc9 · 2019-07-02T21:50:16.000-04:00
DOC: Format parameters in descriptions with emph instead of backticks
diff --git a/examples/axes_grid1/inset_locator_demo.py b/examples/axes_grid1/inset_locator_demo.py
@@ -11,7 +11,7 @@
 # height and optionally a location (loc) that accepts locations as codes,
 # similar to `~matplotlib.axes.Axes.legend`.
 # By default, the inset is offset by some points from the axes,
-# controlled via the `borderpad` parameter.
+# controlled via the *borderpad* parameter.
 
 import matplotlib.pyplot as plt
 from mpl_toolkits.axes_grid1.inset_locator import inset_axes
@@ -44,11 +44,11 @@
 
 
 ###############################################################################
-# The arguments `bbox_to_anchor` and `bbox_transfrom` can be used for a more
+# The arguments *bbox_to_anchor* and *bbox_transfrom* can be used for a more
 # fine grained control over the inset position and size or even to position
 # the inset at completely arbitrary positions.
-# The `bbox_to_anchor` sets the bounding box in coordinates according to the
-# `bbox_transform`.
+# The *bbox_to_anchor* sets the bounding box in coordinates according to the
+# *bbox_transform*.
 #
 
 fig = plt.figure(figsize=[5.5, 2.8])
diff --git a/examples/statistics/confidence_ellipse.py b/examples/statistics/confidence_ellipse.py
@@ -40,7 +40,7 @@
 
 def confidence_ellipse(x, y, ax, n_std=3.0, facecolor='none', **kwargs):
     """
-    Create a plot of the covariance confidence ellipse of `x` and `y`
+    Create a plot of the covariance confidence ellipse of *x* and *y*.
 
     Parameters
     ----------
diff --git a/lib/matplotlib/_constrained_layout.py b/lib/matplotlib/_constrained_layout.py
@@ -515,7 +515,7 @@ def layoutcolorbarsingle(ax, cax, shrink, aspect, location, pad=0.05):
     """
     Do the layout for a colorbar, to not overly pollute colorbar.py
 
-    `pad` is in fraction of the original axis size.
+    *pad* is in fraction of the original axis size.
     """
     axlb = ax._layoutbox
     axpos = ax._poslayoutbox
@@ -604,7 +604,7 @@ def layoutcolorbargridspec(parents, cax, shrink, aspect, location, pad=0.05):
     """
     Do the layout for a colorbar, to not overly pollute colorbar.py
 
-    `pad` is in fraction of the original axis size.
+    *pad* is in fraction of the original axis size.
     """
 
     gs = parents[0].get_subplotspec().get_gridspec()
diff --git a/lib/matplotlib/_layoutbox.py b/lib/matplotlib/_layoutbox.py
@@ -319,10 +319,10 @@ def edit_width(self, width, strength='strong'):
         sol.suggestValue(self.width, width)
 
     def constrain_width(self, width, strength='strong'):
-        '''
-        Constrain the width of the layout box.  `width` is
+        """
+        Constrain the width of the layout box.  *width* is
         either a float or a layoutbox.width.
-        '''
+        """
         c = (self.width == width)
         self.solver.addConstraint(c | strength)
 
@@ -471,7 +471,7 @@ def __repr__(self):
 def hstack(boxes, padding=0, strength='strong'):
     '''
     Stack LayoutBox instances from left to right.
-    `padding` is in figure-relative units.
+    *padding* is in figure-relative units.
     '''
 
     for i in range(1, len(boxes)):
diff --git a/lib/matplotlib/artist.py b/lib/matplotlib/artist.py
@@ -681,7 +681,7 @@ def set_figure(self, fig):
         if self.figure is fig:
             return
         # if we currently have a figure (the case of both `self.figure`
-        # and `fig` being none is taken care of above) we then user is
+        # and *fig* being none is taken care of above) we then user is
         # trying to change the figure an artist is associated with which
         # is not allowed for the same reason as adding the same instance
         # to more than one Axes
@@ -1518,7 +1518,7 @@ def setp(obj, *args, **kwargs):
           ... long output listing omitted
 
     You may specify another output file to `setp` if `sys.stdout` is not
-    acceptable for some reason using the `file` keyword-only argument::
+    acceptable for some reason using the *file* keyword-only argument::
 
       >>> with fopen('output.log') as f:
       >>>     setp(line, file=f)
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -160,7 +160,7 @@ def set_title(self, label, fontdict=None, loc=None, pad=None,
 
         fontdict : dict
             A dictionary controlling the appearance of the title text,
-            the default `fontdict` is::
+            the default *fontdict* is::
 
                {'fontsize': rcParams['axes.titlesize'],
                 'fontweight' : rcParams['axes.titleweight'],
@@ -723,7 +723,7 @@ def text(self, x, y, s, fontdict=None, withdash=False, **kwargs):
             ...      verticalalignment='center', transform=ax.transAxes)
 
         You can put a rectangular box around the text instance (e.g., to
-        set a background color) by using the keyword `bbox`.  `bbox` is
+        set a background color) by using the keyword *bbox*.  *bbox* is
         a dictionary of `~matplotlib.patches.Rectangle`
         properties.  For example::
 
@@ -967,8 +967,8 @@ 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
+        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,
@@ -3680,7 +3680,7 @@ def boxplot(self, x, notch=None, sym=None, vert=None, whis=None,
         # if non-default sym value, put it into the flier dictionary
         # the logic for providing the default symbol ('b+') now lives
         # in bxp in the initial value of final_flierprops
-        # handle all of the `sym` related logic here so we only have to pass
+        # handle all of the *sym* related logic here so we only have to pass
         # on the flierprops dict.
         if sym is not None:
             # no-flier case, which should really be done with
@@ -6351,12 +6351,12 @@ def hist(self, x, bins=None, range=None, density=False, weights=None,
             If an integer is given, ``bins + 1`` bin edges are calculated and
             returned, consistent with `numpy.histogram`.
 
-            If `bins` is a sequence, gives bin edges, including left edge of
-            first bin and right edge of last bin.  In this case, `bins` is
+            If *bins* is a sequence, gives bin edges, including left edge of
+            first bin and right edge of last bin.  In this case, *bins* is
             returned unmodified.
 
             All but the last (righthand-most) bin is half-open.  In other
-            words, if `bins` is::
+            words, if *bins* is::
 
                 [1, 2, 3, 4]
 
@@ -7911,7 +7911,7 @@ def violin(self, vpstats, positions=None, vert=True, widths=0.5,
                showmeans=False, showextrema=True, showmedians=False):
         """Drawing function for violin plots.
 
-        Draw a violin plot for each column of `vpstats`. Each filled area
+        Draw a violin plot for each column of *vpstats*. Each filled area
         extends to represent the entire data range, with optional lines at the
         mean, the median, the minimum, the maximum, and the quantiles values.
 
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -3387,7 +3387,7 @@ def get_xticklabels(self, minor=False, which=None):
            else return the major ticklabels.
 
         which : None, ('minor', 'major', 'both')
-           Overrides `minor`.
+           Overrides *minor*.
 
            Selects which ticklabels to return
 
@@ -3411,7 +3411,7 @@ def set_xticklabels(self, labels, fontdict=None, minor=False, **kwargs):
 
         fontdict : dict, optional
             A dictionary controlling the appearance of the ticklabels.
-            The default `fontdict` is::
+            The default *fontdict* is::
 
                {'fontsize': rcParams['axes.titlesize'],
                 'fontweight': rcParams['axes.titleweight'],
@@ -3770,7 +3770,7 @@ def get_yticklabels(self, minor=False, which=None):
            else return the major ticklabels
 
         which : None, ('minor', 'major', 'both')
-           Overrides `minor`.
+           Overrides *minor*.
 
            Selects which ticklabels to return
 
@@ -3794,7 +3794,7 @@ def set_yticklabels(self, labels, fontdict=None, minor=False, **kwargs):
 
         fontdict : dict, optional
             A dictionary controlling the appearance of the ticklabels.
-            The default `fontdict` is::
+            The default *fontdict* is::
 
                {'fontsize': rcParams['axes.titlesize'],
                 'fontweight': rcParams['axes.titleweight'],
diff --git a/lib/matplotlib/axis.py b/lib/matplotlib/axis.py
@@ -1295,7 +1295,7 @@ def get_ticklabels(self, minor=False, which=None):
            else return the major ticklabels
 
         which : None, ('minor', 'major', 'both')
-           Overrides `minor`.
+           Overrides *minor*.
 
            Selects which ticklabels to return
 
diff --git a/lib/matplotlib/backend_bases.py b/lib/matplotlib/backend_bases.py
@@ -481,9 +481,9 @@ def draw_image(self, gc, x, y, im, transform=None):
             form of a :class:`~matplotlib.transforms.Affine2DBase` instance.
             The translation vector of the transformation is given in physical
             units (i.e., dots or pixels). Note that the transformation does not
-            override `x` and `y`, and has to be applied *before* translating
-            the result by `x` and `y` (this can be accomplished by adding `x`
-            and `y` to the translation vector defined by `transform`).
+            override *x* and *y*, and has to be applied *before* translating
+            the result by *x* and *y* (this can be accomplished by adding *x*
+            and *y* to the translation vector defined by *transform*).
         """
         raise NotImplementedError
 
@@ -1000,10 +1000,10 @@ def get_sketch_params(self):
 
             A 3-tuple with the following elements:
 
-            * `scale`: The amplitude of the wiggle perpendicular to the
+            * ``scale``: The amplitude of the wiggle perpendicular to the
               source line.
-            * `length`: The length of the wiggle along the line.
-            * `randomness`: The scale factor by which the length is
+            * ``length``: The length of the wiggle along the line.
+            * ``randomness``: The scale factor by which the length is
               shrunken or expanded.
 
             May return `None` if no sketch parameters were set.
diff --git a/lib/matplotlib/backend_tools.py b/lib/matplotlib/backend_tools.py
@@ -75,7 +75,7 @@ class ToolBase:
     Filename of the image
 
     **String**: Filename of the image to use in the toolbar. If None, the
-    `name` is used as a label in the toolbar button
+    *name* is used as a label in the toolbar button
     """
 
     def __init__(self, toolmanager, name):
diff --git a/lib/matplotlib/backends/backend_pgf.py b/lib/matplotlib/backends/backend_pgf.py
@@ -1075,7 +1075,7 @@ def __exit__(self, exc_type, exc_val, exc_tb):
     def close(self):
         """
         Finalize this object, running LaTeX in a temporary directory
-        and moving the final pdf file to `filename`.
+        and moving the final pdf file to *filename*.
         """
         self._file.write(rb'\end{document}\n')
         self._file.close()
diff --git a/lib/matplotlib/backends/qt_editor/figureoptions.py b/lib/matplotlib/backends/qt_editor/figureoptions.py
@@ -78,9 +78,9 @@ def cmp_key(label):
     def prepare_data(d, init):
         """Prepare entry for FormLayout.
 
-        `d` is a mapping of shorthands to style names (a single style may
+        *d* is a mapping of shorthands to style names (a single style may
         have multiple shorthands, in particular the shorthands `None`,
-        `"None"`, `"none"` and `""` are synonyms); `init` is one shorthand
+        `"None"`, `"none"` and `""` are synonyms); *init* is one shorthand
         of the initial style.
 
         This function returns an list suitable for initializing a
diff --git a/lib/matplotlib/cbook/__init__.py b/lib/matplotlib/cbook/__init__.py
@@ -1083,7 +1083,7 @@ def boxplot_stats(X, whis=1.5, bootstrap=None, labels=None,
 
     labels : array-like, optional
         Labels for each dataset. Length must be compatible with
-        dimensions of `X`.
+        dimensions of *X*.
 
     autorange : bool, optional (False)
         When `True` and the data are distributed such that the 25th and 75th
@@ -1478,7 +1478,7 @@ def pts_to_prestep(x, *args):
     >>> x_s, y1_s, y2_s = pts_to_prestep(x, y1, y2)
     """
     steps = np.zeros((1 + len(args), max(2 * len(x) - 1, 0)))
-    # In all `pts_to_*step` functions, only assign *once* using `x` and `args`,
+    # In all `pts_to_*step` functions, only assign once using *x* and *args*,
     # as converting to an array may be expensive.
     steps[0, 0::2] = x
     steps[0, 1::2] = steps[0, 0:-2:2]
diff --git a/lib/matplotlib/dates.py b/lib/matplotlib/dates.py
@@ -291,7 +291,7 @@ def _from_ordinalf(x, tz=None):
                          'expects datetime objects.'.format(ix))
     dt = datetime.datetime.fromordinal(ix).replace(tzinfo=UTC)
 
-    # Since the input date `x` float is unable to preserve microsecond
+    # Since the input date *x* float is unable to preserve microsecond
     # precision of time representation in non-antique years, the
     # resulting datetime is rounded to the nearest multiple of
     # `musec_prec`. A value of 20 is appropriate for current dates.
diff --git a/lib/matplotlib/legend.py b/lib/matplotlib/legend.py
@@ -185,7 +185,7 @@ def _update_bbox_to_anchor(self, loc_in_canvas):
     Controls the font size of the legend. If the value is numeric the
     size will be the absolute font size in points. String values are
     relative to the current default font size. This argument is only
-    used if `prop` is not specified.
+    used if *prop* is not specified.
 
 numpoints : None or int
     The number of marker points in the legend when creating a legend
@@ -254,7 +254,7 @@ def _update_bbox_to_anchor(self, loc_in_canvas):
     :rc:`axes.edgecolor`.
 
 mode : {"expand", None}
-    If `mode` is set to ``"expand"`` the legend will be horizontally
+    If *mode* is set to ``"expand"`` the legend will be horizontally
     expanded to fill the axes area (or `bbox_to_anchor` if defines
     the legend's size).
 
diff --git a/lib/matplotlib/mlab.py b/lib/matplotlib/mlab.py
@@ -1427,11 +1427,11 @@ class GaussianKDE:
         the covariance matrix is multiplied.
 
     covariance : ndarray
-        The covariance matrix of `dataset`, scaled by the calculated bandwidth
+        The covariance matrix of *dataset*, scaled by the calculated bandwidth
         (`kde.factor`).
 
     inv_cov : ndarray
-        The inverse of `covariance`.
+        The inverse of *covariance*.
 
     Methods
     -------
diff --git a/lib/matplotlib/path.py b/lib/matplotlib/path.py
@@ -460,7 +460,7 @@ def contains_point(self, point, transform=None, radius=0.0):
         if transform is not None:
             transform = transform.frozen()
         # `point_in_path` does not handle nonlinear transforms, so we
-        # transform the path ourselves.  If `transform` is affine, letting
+        # transform the path ourselves.  If *transform* is affine, letting
         # `point_in_path` handle the transform avoids allocating an extra
         # buffer.
         if transform and not transform.is_affine:
diff --git a/lib/matplotlib/patheffects.py b/lib/matplotlib/patheffects.py
@@ -292,7 +292,7 @@ def __init__(self, offset=(2, -2),
         shadow_color : color
             The shadow color. Default is black.
             A value of ``None`` takes the original artist's color
-            with a scale factor of `rho`.
+            with a scale factor of *rho*.
         alpha : float
             The alpha transparency of the created shadow patch.
             Default is 0.3.
diff --git a/lib/matplotlib/pyplot.py b/lib/matplotlib/pyplot.py
@@ -445,7 +445,7 @@ def figure(num=None,  # autoincrement if None, else integer from 1-N
         it active, and returns a reference to it. If this figure does not
         exists, create it and returns it.
         If num is a string, the window title will be set to this figure's
-        `num`.
+        *num*.
 
     figsize : (float, float), optional, default: None
         width, height in inches. If not provided, defaults to
diff --git a/lib/matplotlib/sphinxext/plot_directive.py b/lib/matplotlib/sphinxext/plot_directive.py
@@ -71,7 +71,7 @@
         inserted.  This is usually useful with the ``:context:`` option.
 
 Additionally, this directive supports all of the options of the `image`
-directive, except for `target` (since plot will add its own target).  These
+directive, except for *target* (since plot will add its own target).  These
 include `alt`, `height`, `width`, `scale`, `align` and `class`.
 
 Configuration options
diff --git a/lib/matplotlib/streamplot.py b/lib/matplotlib/streamplot.py
@@ -352,7 +352,7 @@ def shape(self):
     def within_grid(self, xi, yi):
         """Return True if point is a valid index of grid."""
         # Note that xi/yi can be floats; so, for example, we can't simply check
-        # `xi < self.nx` since `xi` can be `self.nx - 1 < xi < self.nx`
+        # `xi < self.nx` since *xi* can be `self.nx - 1 < xi < self.nx`
         return xi >= 0 and xi <= self.nx - 1 and yi >= 0 and yi <= self.ny - 1
 
 
diff --git a/lib/matplotlib/testing/compare.py b/lib/matplotlib/testing/compare.py
@@ -24,8 +24,7 @@
 
 def make_test_filename(fname, purpose):
     """
-    Make a new filename by inserting `purpose` before the file's
-    extension.
+    Make a new filename by inserting *purpose* before the file's extension.
     """
     base, ext = os.path.splitext(fname)
     return '%s-%s%s' % (base, purpose, ext)
diff --git a/lib/matplotlib/testing/decorators.py b/lib/matplotlib/testing/decorators.py
@@ -56,7 +56,7 @@ def cleanup(style=None):
         The name of the style to apply.
     """
 
-    # If cleanup is used without arguments, `style` will be a callable, and we
+    # If cleanup is used without arguments, *style* will be a callable, and we
     # pass it directly to the wrapper generator.  If cleanup if called with an
     # argument, it is a string naming a style, and the function will be passed
     # as an argument to what we return.  This is a confusing, but somewhat
diff --git a/lib/matplotlib/tests/test_artist.py b/lib/matplotlib/tests/test_artist.py
@@ -238,7 +238,7 @@ def test_setp():
     martist.setp(chain(lines1, lines2), 'lw', 5)
     plt.setp(ax.spines.values(), color='green')
 
-    # Check `file` argument
+    # Check *file* argument
     sio = io.StringIO()
     plt.setp(lines1, 'zorder', file=sio)
     assert sio.getvalue() == '  zorder: float\n'
diff --git a/lib/matplotlib/text.py b/lib/matplotlib/text.py
diff --git a/lib/matplotlib/ticker.py b/lib/matplotlib/ticker.py
diff --git a/lib/matplotlib/tri/triangulation.py b/lib/matplotlib/tri/triangulation.py
diff --git a/lib/matplotlib/tri/triinterpolate.py b/lib/matplotlib/tri/triinterpolate.py
