Split apart and numpydoc tricontour[f] docs.

QuLogic · QuLogic · commit f6ee5df94547 · 2020-06-24T22:00:49.000-04:00
While they are fairly similar, they do have a reasonable amount of
differing parameters.
diff --git a/lib/matplotlib/tri/tricontour.py b/lib/matplotlib/tri/tricontour.py
@@ -1,5 +1,6 @@
 import numpy as np
 
+from matplotlib import docstring
 from matplotlib.contour import ContourSet
 from matplotlib.tri.triangulation import Triangulation
 
@@ -107,175 +108,164 @@ def _contour_args(self, args, kwargs):
         return (tri, z)
 
 
-def tricontour(ax, *args, **kwargs):
-    """
-    Draw contours on an unstructured triangular grid.
-
-    `.tricontour` and `.tricontourf` draw contour lines and filled contours,
-    respectively.  Except as noted, function signatures and return values are
-    the same for both versions.
-
-    The triangulation can be specified in one of two ways; either ::
-
-        tricontour(triangulation, ...)
-
-    where *triangulation* is a `.Triangulation` object, or ::
+docstring.interpd.update(_tricontour_doc="""
+Draw contour %(type)s on an unstructured triangular grid.
 
-        tricontour(x, y, ...)
-        tricontour(x, y, triangles, ...)
-        tricontour(x, y, triangles=triangles, ...)
-        tricontour(x, y, mask=mask, ...)
-        tricontour(x, y, triangles, mask=mask, ...)
+The triangulation can be specified in one of two ways; either ::
 
-    in which case a `.Triangulation` object will be created.  See that class'
-    docstring for an explanation of these cases.
+    %(func)s(triangulation, ...)
 
-    The remaining arguments may be::
+where *triangulation* is a `.Triangulation` object, or ::
 
-        tricontour(..., Z)
+    %(func)s(x, y, ...)
+    %(func)s(x, y, triangles, ...)
+    %(func)s(x, y, triangles=triangles, ...)
+    %(func)s(x, y, mask=mask, ...)
+    %(func)s(x, y, triangles, mask=mask, ...)
 
-    where *Z* is the array of values to contour, one per point in the
-    triangulation.  The level values are chosen automatically.
+in which case a `.Triangulation` object will be created.  See that class'
+docstring for an explanation of these cases.
 
-    ::
+The remaining arguments may be::
 
-        tricontour(..., Z, N)
+    %(func)s(..., Z)
 
-    contour up to *N+1* automatically chosen contour levels (*N* intervals).
+where *Z* is the array of values to contour, one per point in the
+triangulation.  The level values are chosen automatically.
 
-    ::
+::
 
-        tricontour(..., Z, V)
+    %(func)s(..., Z, N)
 
-    draw contour lines at the values specified in sequence *V*,
-    which must be in increasing order.
+contour up to *N+1* automatically chosen contour levels (*N* intervals).
 
-    ::
+::
 
-        tricontourf(..., Z, V)
+    %(func)s(..., Z, V)
 
-    fill the (len(*V*)-1) regions between the values in *V*,
-    which must be in increasing order.
+draw contour %(type)s at the values specified in sequence *V*, which must be in
+increasing order.
 
-    ::
+::
 
-        tricontour(Z, **kwargs)
+    %(func)s(Z, **kwargs)
 
-    Use keyword args to control colors, linewidth, origin, cmap ... see
-    below for more details.
+Use keyword arguments to control colors, linewidth, origin, cmap ... see below
+for more details.
 
-    `~.Axes.tricontour` returns a `~matplotlib.tri.TriContourSet` object.
+Returns
+-------
+`~matplotlib.tri.TriContourSet`
 
-    Optional keyword arguments:
+Other Parameters
+----------------
+colors : [ *None* | str | (mpl_colors) ]
+    If *None*, the colormap specified by cmap will be used.
 
-        *colors*: [ *None* | str | (mpl_colors) ]
-        If *None*, the colormap specified by cmap will be used.
+    If a string, like 'r' or 'red', all levels will be plotted in this color.
 
-        If a string, like 'r' or 'red', all levels will be plotted in this
-        color.
+    If a tuple of colors (string, float, rgb, etc), different levels will be
+    plotted in different colors in the order specified.
 
-        If a tuple of colors (string, float, rgb, etc), different levels will
-        be plotted in different colors in the order specified.
+alpha : float
+    The alpha blending value
 
-        *alpha*: float
-        The alpha blending value
+cmap : [ *None* | Colormap ]
+    A cm :class:`~matplotlib.colors.Colormap` instance or *None*. If *cmap* is
+    *None* and *colors* is *None*, a default Colormap is used.
 
-        *cmap*: [ *None* | Colormap ]
-        A cm :class:`~matplotlib.colors.Colormap` instance or
-        *None*. If *cmap* is *None* and *colors* is *None*, a
-        default Colormap is used.
+norm : [ *None* | Normalize ]
+    A :class:`matplotlib.colors.Normalize` instance for scaling data values to
+    colors. If *norm* is *None* and *colors* is *None*, the default linear
+    scaling is used.
 
-        *norm*: [ *None* | Normalize ]
-        A :class:`matplotlib.colors.Normalize` instance for
-        scaling data values to colors. If *norm* is *None* and
-        *colors* is *None*, the default linear scaling is used.
+levels : [level0, level1, ..., leveln]
+    A list of floating point numbers indicating the level curves to draw, in
+    increasing order; e.g., to draw just the zero contour pass ``levels=[0]``
 
-        *levels* [level0, level1, ..., leveln]
-        A list of floating point numbers indicating the level
-        curves to draw, in increasing order; e.g., to draw just
-        the zero contour pass ``levels=[0]``
+origin : [ *None* | 'upper' | 'lower' | 'image' ]
+    If *None*, the first value of *Z* will correspond to the lower left corner,
+    location (0, 0). If 'image', the rc value for ``image.origin`` will be
+    used.
 
-        *origin*: [ *None* | 'upper' | 'lower' | 'image' ]
-        If *None*, the first value of *Z* will correspond to the
-        lower left corner, location (0, 0). If 'image', the rc
-        value for ``image.origin`` will be used.
+    This keyword is not active if *X* and *Y* are specified in the call to
+    contour.
 
-        This keyword is not active if *X* and *Y* are specified in
-        the call to contour.
+extent : [ *None* | (x0, x1, y0, y1) ]
+    If *origin* is not *None*, then *extent* is interpreted as in
+    :func:`matplotlib.pyplot.imshow`: it gives the outer pixel boundaries. In
+    this case, the position of Z[0, 0] is the center of the pixel, not a
+    corner. If *origin* is *None*, then (*x0*, *y0*) is the position of Z[0,
+    0], and (*x1*, *y1*) is the position of Z[-1, -1].
 
-        *extent*: [ *None* | (x0, x1, y0, y1) ]
+    This keyword is not active if *X* and *Y* are specified in the call to
+    contour.
 
-        If *origin* is not *None*, then *extent* is interpreted as
-        in :func:`matplotlib.pyplot.imshow`: it gives the outer
-        pixel boundaries. In this case, the position of Z[0, 0]
-        is the center of the pixel, not a corner. If *origin* is
-        *None*, then (*x0*, *y0*) is the position of Z[0, 0], and
-        (*x1*, *y1*) is the position of Z[-1, -1].
+locator : [ *None* | ticker.Locator subclass ]
+    If *locator* is None, the default :class:`~matplotlib.ticker.MaxNLocator`
+    is used. The locator is used to determine the contour levels if they are
+    not given explicitly via the *V* argument.
 
-        This keyword is not active if *X* and *Y* are specified in
-        the call to contour.
+extend : [ 'neither' | 'both' | 'min' | 'max' ]
+    Unless this is 'neither', contour levels are automatically added to one or
+    both ends of the range so that all data are included. These added ranges
+    are then mapped to the special colormap values which default to the ends of
+    the colormap range, but can be set via
+    :meth:`matplotlib.colors.Colormap.set_under` and
+    :meth:`matplotlib.colors.Colormap.set_over` methods.
 
-        *locator*: [ *None* | ticker.Locator subclass ]
-        If *locator* is None, the default
-        :class:`~matplotlib.ticker.MaxNLocator` is used. The
-        locator is used to determine the contour levels if they
-        are not given explicitly via the *V* argument.
+xunits, yunits : [ *None* | registered units ]
+    Override axis units by specifying an instance of a
+    :class:`matplotlib.units.ConversionInterface`.""")
 
-        *extend*: [ 'neither' | 'both' | 'min' | 'max' ]
-        Unless this is 'neither', contour levels are automatically
-        added to one or both ends of the range so that all data
-        are included. These added ranges are then mapped to the
-        special colormap values which default to the ends of the
-        colormap range, but can be set via
-        :meth:`matplotlib.colors.Colormap.set_under` and
-        :meth:`matplotlib.colors.Colormap.set_over` methods.
 
-        *xunits*, *yunits*: [ *None* | registered units ]
-        Override axis units by specifying an instance of a
-        :class:`matplotlib.units.ConversionInterface`.
-
-    tricontour-only keyword arguments:
+@docstring.Substitution(func='tricontour', type='lines')
+@docstring.dedent_interpd
+def tricontour(ax, *args, **kwargs):
+    """
+    %(_tricontour_doc)s
 
-        *linewidths*: [ *None* | number | tuple of numbers ]
+    linewidths : [ *None* | number | tuple of numbers ]
         If *linewidths* is *None*, defaults to :rc:`lines.linewidth`.
 
         If a number, all levels will be plotted with this linewidth.
 
-        If a tuple, different levels will be plotted with different
-        linewidths in the order specified
+        If a tuple, different levels will be plotted with different linewidths
+        in the order specified
 
-        *linestyles*: [ *None* | 'solid' | 'dashed' | 'dashdot' | 'dotted' ]
+    linestyles : [ *None* | 'solid' | 'dashed' | 'dashdot' | 'dotted' ]
         If *linestyles* is *None*, the 'solid' is used.
 
-        *linestyles* can also be an iterable of the above strings
-        specifying a set of linestyles to be used. If this
-        iterable is shorter than the number of contour levels
-        it will be repeated as necessary.
+        *linestyles* can also be an iterable of the above strings specifying a
+        set of linestyles to be used. If this iterable is shorter than the
+        number of contour levels it will be repeated as necessary.
+
+        If contour is using a monochrome colormap and the contour level is less
+        than 0, then the linestyle specified in
+        :rc:`contour.negative_linestyle` will be used.
+    """
+    kwargs['filled'] = False
+    return TriContourSet(ax, *args, **kwargs)
 
-        If contour is using a monochrome colormap and the contour
-        level is less than 0, then the linestyle specified
-        in :rc:`contour.negative_linestyle` will be used.
 
-    tricontourf-only keyword arguments:
+@docstring.Substitution(func='tricontourf', type='regions')
+@docstring.dedent_interpd
+def tricontourf(ax, *args, **kwargs):
+    """
+    %(_tricontour_doc)s
 
-        *antialiased*: bool
+    antialiased : bool
         enable antialiasing
 
-    Note: `.tricontourf` fills intervals that are closed at the top; that is,
-    for boundaries *z1* and *z2*, the filled region is::
+    Notes
+    -----
+    `.tricontourf` fills intervals that are closed at the top; that is, for
+    boundaries *z1* and *z2*, the filled region is::
 
         z1 < Z <= z2
 
     except for the lowest interval, which is closed on both sides (i.e. it
     includes the lowest value).
     """
-    kwargs['filled'] = False
-    return TriContourSet(ax, *args, **kwargs)
-
-
-def tricontourf(ax, *args, **kwargs):
     kwargs['filled'] = True
     return TriContourSet(ax, *args, **kwargs)
-
-
-tricontourf.__doc__ = tricontour.__doc__
