STY: Clean up docstrings.

skimage/measure/find_contours.py

@@ -5,8 +5,9 @@ from collections import deque
 
 _param_options = ('high', 'low')
 
-def find_contours(array, level, fully_connected='low', positive_orientation='low'):
-    '''Find iso-valued contours in a 2D array for a given level value.
+def find_contours(array, level,
+                  fully_connected='low', positive_orientation='low'):
+    """Find iso-valued contours in a 2D array for a given level value.
 
     Uses the "marching squares" method to compute a the iso-valued contours of
     the input 2D array for a particular level value. Array values are linearly
@@ -14,35 +15,36 @@ def find_contours(array, level, fully_connected='low', positive_orientation='low
 
     Parameters
     ----------
-    array : convertible to a 2D ndarray object
-        Input data in which to find isocontours.
+    array : 2D ndarray of double
+        Input data in which to find contours.
     level : float
         Value along which to find contours in the array.
-    fully_connected : either 'low' or 'high'
-         Indicates whether array elements below the given level value are to
-         be considered fully- connected (and hence elements above the value
-         will only be face connected), or vice-versa. (See below for details.)
+    fully_connected : str, {'low', 'high'}
+         Indicates whether array elements below the given level value are to be
+         considered fully-connected (and hence elements above the value will
+         only be face connected), or vice-versa. (See notes below for details.)
     positive_orientation : either 'low' or 'high'
-         Indicates whether the output contours will produce
-         positively-oriented polygons around islands of low- or high-valued
-         elements. If 'low' then contours will wind counter- clockwise around
-         elements below the iso-value. Alternately, this means that low-valued
-         elements are always on the left of the contour. (See below for
-         details.)
+         Indicates whether the output contours will produce positively-oriented
+         polygons around islands of low- or high-valued elements. If 'low' then
+         contours will wind counter- clockwise around elements below the
+         iso-value. Alternately, this means that low-valued elements are always
+         on the left of the contour. (See below for details.)
 
     Returns
     -------
-    A list of contours, where each contour is an ndarray of shape (n, 2)
-    consisting of n (x,y) coordinates along the contour.
+    contours : list of (n,2)-ndarrays
+        Each contour is an ndarray of shape ``(n, 2)``,
+        consisting of n ``(x, y)`` coordinates along the contour.
 
+    Notes
+    -----
     The marching squares algorithm is a special case of the marching cubes
-    algorithm (Lorensen, William and Harvey E. Cline. Marching Cubes: A High
-    Resolution 3D Surface Construction Algorithm. Computer Graphics (SIGGRAPH
-    87 Proceedings) 21(4) July 1987, p. 163-170). A simple explanation is
-    available here: http://www.essi.fr/~lingrand/MarchingCubes/algo.html
+    algorithm [1]_.  A simple explanation is available here::
+
+      http://www.essi.fr/~lingrand/MarchingCubes/algo.html
 
     There is a single ambiguous case in the marching squares algorithm: when
-    a given 2x2-element square has two high-valued and two low-valued
+    a given ``2 x 2``-element square has two high-valued and two low-valued
     elements, each pair diagonally adjacent. (Where high- and low-valued is
     with respect to the contour value sought.) In this case, either the
     high-valued elements can be 'connected together' via a thin isthmus that
@@ -50,7 +52,7 @@ def find_contours(array, level, fully_connected='low', positive_orientation='low
     connected together across a diagonal, they are considered 'fully
     connected' (also known as 'face+vertex-connected' or '8-connected'). Only
     high-valued or low-valued elements can be fully-connected, the other set
-    will be considred as 'face-connected' or '4-connected'. By default,
+    will be considered as 'face-connected' or '4-connected'. By default,
     low-valued elements are considered fully-connected; this can be altered
     with the 'fully_connected' parameter.
 
@@ -67,23 +69,32 @@ def find_contours(array, level, fully_connected='low', positive_orientation='low
     'positive_orientation' parameter.
 
     The order of the contours in the output list is determined by the position
-    of the smallest x,y (in lexicographical order) coordinate in the contour.
-    This is a side-effect of how the input array is traversed, but can be
-    relied upon.
+    of the smallest ``x,y`` (in lexicographical order) coordinate in the
+    contour.  This is a side-effect of how the input array is traversed, but
+    can be relied upon.
 
-    IMPORTANT NOTE ON COORDINATES AND VALUES:
-    Array coordinates/values are assumed to refer to the _center_ of the
-    array element. Take a simple example: [0, 1]. The interpolated position of
-    0.5 in this array is midway between the 0-element (at x=0) and the
-    1-element (at x=1), and thus would fall at x=0.5.
+    .. warning::
+
+       Array coordinates/values are assumed to refer to the *center* of the
+       array element. Take a simple example input: ``[0, 1]``. The interpolated
+       position of 0.5 in this array is midway between the 0-element (at
+       ``x=0``) and the 1-element (at ``x=1``), and thus would fall at
+       ``x=0.5``.
 
     This means that to find reasonable contours, it is best to find contours
     midway between the expected "light" and "dark" values. In particular,
-    given a binarized array, DO NOT choose to find contours at the low or high
+    given a binarized array, *do not* choose to find contours at the low or high
     value of the array. This will often yield degenerate contours, especially
     around structures that are a single array element wide. Instead choose
-    a middle value, as above.'''
+    a middle value, as above.
 
+    References
+    ----------
+    .. [1] Lorensen, William and Harvey E. Cline. Marching Cubes: A High
+           Resolution 3D Surface Construction Algorithm. Computer Graphics
+           (SIGGRAPH 87 Proceedings) 21(4) July 1987, p. 163-170).
+
+    """
     array = np.asarray(array, dtype=np.double)
     if array.ndim != 2:
         raise RuntimeError('Only 2D arrays are supported.')