Merge pull request matplotlib#12897 from anntzer/contour-docs

jklymak · web-flow · commit d42a0a85e91a · 2018-11-27T13:08:49.000-08:00
Reword a bit the contour docs.
diff --git a/lib/matplotlib/contour.py b/lib/matplotlib/contour.py
@@ -1661,19 +1661,17 @@ def _initialize_x_y(self, z):
 
             contour([X, Y,] Z, [levels], **kwargs)
 
-        :func:`~matplotlib.pyplot.contour` and
-        :func:`~matplotlib.pyplot.contourf` draw contour lines and
-        filled contours, respectively.  Except as noted, function
-        signatures and return values are the same for both versions.
-
+        `.contour` and `.contourf` draw contour lines and filled contours,
+        respectively.  Except as noted, function signatures and return values
+        are the same for both versions.
 
         Parameters
         ----------
         X, Y : array-like, optional
             The coordinates of the values in *Z*.
 
             *X* and *Y* must both be 2-D with the same shape as *Z* (e.g.
-            created via :func:`numpy.meshgrid`), or they must both be 1-D such
+            created via `numpy.meshgrid`), or they must both be 1-D such
             that ``len(X) == M`` is the number of columns in *Z* and
             ``len(Y) == N`` is the number of rows in *Z*.
 
@@ -1705,8 +1703,7 @@ def _initialize_x_y(self, z):
             nearest those points are always masked out, other triangular
             corners comprising three unmasked points are contoured as usual.
 
-            Defaults to ``rcParams['contour.corner_mask']``, which defaults to
-            ``True``.
+            Defaults to :rc:`contour.corner_mask`, which defaults to ``True``.
 
         colors : color string or sequence of colors, optional
             The colors of the levels, i.e. the lines for `.contour` and the
@@ -1755,15 +1752,14 @@ def _initialize_x_y(self, z):
             - 'image': Use the value from :rc:`image.origin`.
 
         extent : (x0, x1, y0, y1), optional
-            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].
+            If *origin* is not *None*, then *extent* is interpreted as in
+            `.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].
 
-            This keyword is not active if *X* and *Y* are specified in
-            the call to contour.
+            This argument is ignored if *X* and *Y* are specified in the call
+            to contour.
 
         locator : ticker.Locator subclass, optional
             The locator is used to determine the contour levels if they
@@ -1829,20 +1825,17 @@ def _initialize_x_y(self, z):
             Hatching is supported in the PostScript, PDF, SVG and Agg
             backends only.
 
-
         Notes
         -----
-        1. :func:`~matplotlib.pyplot.contourf` differs from the MATLAB
-           version in that it does not draw the polygon edges.
-           To draw edges, add line contours with
-           calls to :func:`~matplotlib.pyplot.contour`.
+        1. `.contourf` differs from the MATLAB version in that it does not draw
+           the polygon edges. To draw edges, add line contours with calls to
+           `.contour`.
 
-        2. contourf fills intervals that are closed at the top; that
-           is, for boundaries *z1* and *z2*, the filled region is::
+        2. `.contourf` fills intervals that are closed at the top; that is, for
+           boundaries *z1* and *z2*, the filled region is::
 
               z1 < Z <= z2
 
-           There is one exception: if the lowest boundary coincides with
-           the minimum value of the *Z* array, then that minimum value
-           will be included in the lowest interval.
+           except for the lowest interval, which is closed on both sides (i.e.
+           it includes the lowest value).
         """
diff --git a/lib/matplotlib/tri/tricontour.py b/lib/matplotlib/tri/tricontour.py
@@ -94,44 +94,38 @@ def _contour_args(self, args, kwargs):
 def tricontour(ax, *args, **kwargs):
     """
     Draw contours on an unstructured triangular grid.
-    :func:`~matplotlib.pyplot.tricontour` and
-    :func:`~matplotlib.pyplot.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` and `.tricontourf` draw contour lines and filled contours,
+    respectively.  Except as noted, function signatures and return values are
+    the same for both versions.
 
-        tricontour(triangulation, ...)
+    The triangulation can be specified in one of two ways; either ::
 
-    where triangulation is a :class:`matplotlib.tri.Triangulation`
-    object, or
+        tricontour(triangulation, ...)
 
-    ::
+    where *triangulation* is a `matplotlib.tri.Triangulation` object, or ::
 
         tricontour(x, y, ...)
         tricontour(x, y, triangles, ...)
         tricontour(x, y, triangles=triangles, ...)
         tricontour(x, y, mask=mask, ...)
         tricontour(x, y, triangles, mask=mask, ...)
 
-    in which case a Triangulation object will be created.  See
-    :class:`~matplotlib.tri.Triangulation` for a explanation of
-    these possibilities.
+    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)
 
-    where *Z* is the array of values to contour, one per point
-    in the triangulation.  The level values are chosen
-    automatically.
+    where *Z* is the array of values to contour, one per point in the
+    triangulation.  The level values are chosen automatically.
 
     ::
 
         tricontour(..., Z, N)
 
-    contour up to *N+1* automatically chosen contour levels
-    (*N* intervals).
+    contour up to *N+1* automatically chosen contour levels (*N* intervals).
 
     ::
 
@@ -154,8 +148,7 @@ def tricontour(ax, *args, **kwargs):
     Use keyword args to control colors, linewidth, origin, cmap ... see
     below for more details.
 
-    ``C = tricontour(...)`` returns a
-    :class:`~matplotlib.contour.TriContourSet` object.
+    `.tricontour(...)` returns a `~matplotlib.contour.TriContourSet` object.
 
     Optional keyword arguments:
 
@@ -226,7 +219,6 @@ def tricontour(ax, *args, **kwargs):
         Override axis units by specifying an instance of a
         :class:`matplotlib.units.ConversionInterface`.
 
-
     tricontour-only keyword arguments:
 
         *linewidths*: [ *None* | number | tuple of numbers ]
@@ -254,14 +246,13 @@ def tricontour(ax, *args, **kwargs):
         *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::
+    Note: `.tricontourf` fills intervals that are closed at the top; that is,
+    for boundaries *z1* and *z2*, the filled region is::
 
-        z1 < z <= z2
+        z1 < Z <= z2
 
-    There is one exception: if the lowest boundary coincides with
-    the minimum value of the *z* array, then that minimum value
-    will be included in the lowest interval.
+    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)
