Improve doc for regular_grid.py

skimage/util/regular_grid.py

@@ -5,7 +5,10 @@ def regular_grid(ar_shape, n_points):
     """Find `n_points` regularly spaced along `ar_shape`.
     
     The returned points (as slices) should be as close to cubically-spaced as
-    possible.
+    possible. Essentially, the points are spaced by the Nth root of the input
+    array size, where N is the number of dimensions. However, if an array
+    dimension cannot fit a full step size, it is "discarded", and the
+    computation is done for only the remaining dimensions.
 
     Parameters
     ----------
@@ -20,6 +23,30 @@ def regular_grid(ar_shape, n_points):
     slices : list of slice objects
         A slice along each dimension of `ar_shape`, such that the intersection
         of all the slices give the coordinates of regularly spaced points.
+
+    Examples
+    --------
+    >>> ar = np.zeros((20, 40))
+    >>> g = regular_grid(ar.shape, 8)
+    >>> g
+    [slice(5.0, None, 10.0), slice(5.0, None, 10.0)]
+    >>> ar[g] = 1
+    >>> ar.sum()
+    8.0
+    >>> ar = np.zeros((20, 40))
+    >>> g = regular_grid(ar.shape, 32)
+    >>> g
+    [slice(2.0, None, 5.0), slice(2.0, None, 5.0)]
+    >>> ar[g] = 1
+    >>> ar.sum()
+    32.0
+    >>> ar = np.zeros((3, 20, 40))
+    >>> g = regular_grid(ar.shape, 8)
+    >>> g
+    [slice(1.0, None, 3.0), slice(5.0, None, 10.0), slice(5.0, None, 10.0)]
+    >>> ar[g] = 1
+    >>> ar.sum()
+    8.0
     """
     ar_shape = np.asanyarray(ar_shape)
     ndim = len(ar_shape)