Merge pull request #23201 from timhoffm/doc-tricontour

greglucas · web-flow · commit e6e63b450d50 · 2022-06-06T20:09:49.000-06:00
Rework tricontour and tricontourf documentation
diff --git a/lib/matplotlib/tri/tricontour.py b/lib/matplotlib/tri/tricontour.py
@@ -84,68 +84,31 @@ def _contour_args(self, args, kwargs):
 _docstring.interpd.update(_tricontour_doc="""
 Draw contour %(type)s on an unstructured triangular grid.
 
-The triangulation can be specified in one of two ways; either ::
+Call signatures::
 
-    %(func)s(triangulation, ...)
+    %(func)s(triangulation, Z, [levels], ...)
+    %(func)s(x, y, Z, [levels], *, [triangles=triangles], [mask=mask], ...)
 
-where *triangulation* is a `.Triangulation` object, or ::
+The triangular grid can be specified either by passing a `.Triangulation`
+object as the first parameter, or by passing the points *x*, *y* and
+optionally the *triangles* and a *mask*. See `.Triangulation` for an
+explanation of these parameters. If neither of *triangulation* or
+*triangles* are given, the triangulation is calculated on the fly.
 
-    %(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, ...)
-
-in which case a `.Triangulation` object will be created.  See that class'
-docstring for an explanation of these cases.
-
-The remaining arguments may be::
-
-    %(func)s(..., Z)
-
-where *Z* is the array of values to contour, one per point in the
-triangulation.  The level values are chosen automatically.
-
-::
-
-    %(func)s(..., Z, levels)
-
-contour up to *levels+1* automatically chosen contour levels (*levels*
-intervals).
-
-::
-
-    %(func)s(..., Z, levels)
-
-draw contour %(type)s at the values specified in sequence *levels*, which must
-be in increasing order.
-
-::
-
-    %(func)s(Z, **kwargs)
-
-Use keyword arguments to control colors, linewidth, origin, cmap ... see below
-for more details.
+It is possible to pass *triangles* positionally, i.e.
+``%(func)s(x, y, triangles, Z, ...)``. However, this is discouraged. For more
+clarity, pass *triangles* via keyword argument.
 
 Parameters
 ----------
 triangulation : `.Triangulation`, optional
-    The unstructured triangular grid.
-
-    If specified, then *x*, *y*, *triangles*, and *mask* are not accepted.
-
-x, y : array-like, optional
-    The coordinates of the values in *Z*.
-
-triangles : (ntri, 3) array-like of int, optional
-    For each triangle, the indices of the three points that make up the
-    triangle, ordered in an anticlockwise manner.  If not specified, the
-    Delaunay triangulation is calculated.
+    An already created triangular grid.
 
-mask : (ntri,) array-like of bool, optional
-    Which triangles are masked out.
+x, y, triangles, mask
+    Parameters defining the triangular grid. See `.Triangulation`.
+    This is mutually exclusive with specifying *triangulation*.
 
-Z : 2D array-like
+Z : array-like
     The height values over which the contour is drawn.
 
 levels : int or array-like, optional
diff --git a/lib/matplotlib/tri/tripcolor.py b/lib/matplotlib/tri/tripcolor.py
@@ -21,6 +21,10 @@ def tripcolor(ax, *args, alpha=1.0, norm=None, cmap=None, vmin=None,
     optionally the *triangles* and a *mask*. See `.Triangulation` for an
     explanation of these parameters.
 
+    It is possible to pass the triangles positionally, i.e.
+    ``tripcolor(x, y, triangles, C, ...)``. However, this is discouraged.
+    For more clarity, pass *triangles* via keyword argument.
+
     If neither of *triangulation* or *triangles* are given, the triangulation
     is calculated on the fly. In this case, it does not make sense to provide
     colors at the triangle faces via *C* or *facecolors* because there are
@@ -53,12 +57,6 @@ def tripcolor(ax, *args, alpha=1.0, norm=None, cmap=None, vmin=None,
         defined at points.
     other_parameters
         All other parameters are the same as for `~.Axes.pcolor`.
-
-    Notes
-    -----
-    It is possible to pass the triangles positionally, i.e.
-    ``tripcolor(x, y, triangles, C, ...)``. However, this is discouraged.
-    For more clarity, pass *triangles* via keyword argument.
     """
     _api.check_in_list(['flat', 'gouraud'], shading=shading)
 
