Merge documentation changes from wiki.

4 files changed, 242 insertions, 120 deletions

diff --git a/numpy/lib/arraysetops.py b/numpy/lib/arraysetops.py
index f8304cced..ad8d2d645 100644
--- a/numpy/lib/arraysetops.py
+++ b/numpy/lib/arraysetops.py
@@ -38,23 +38,26 @@ __all__ = ['ediff1d', 'unique1d', 'intersect1d', 'intersect1d_nu', 'setxor1d',
 import time
 import numpy as nm
 
-def ediff1d(ary, to_end = None, to_begin = None):
+def ediff1d(ary, to_end=None, to_begin=None):
     """The differences between consecutive elements of an array, possibly with
     prefixed and/or appended values.
 
-    :Parameters:
-      - `ary` : array
+    Parameters
+    ----------
+    ary : array
         This array will be flattened before the difference is taken.
-      - `to_end` : number, optional
+    to_end : number, optional
         If provided, this number will be tacked onto the end of the returned
         differences.
-      - `to_begin` : number, optional
+    to_begin : number, optional
         If provided, this number will be taked onto the beginning of the
         returned differences.
 
-    :Returns:
-      - `ed` : array
+    Returns
+    -------
+    ed : array
         The differences. Loosely, this will be (ary[1:] - ary[:-1]).
+
     """
     ary = nm.asarray(ary).flat
     ed = ary[1:] - ary[:-1]
@@ -77,22 +80,26 @@ def unique1d(ar1, return_index=False):
     Most of the other array set operations operate on the unique arrays
     generated by this function.
 
-    :Parameters:
-      - `ar1` : array
+    Parameters
+    ----------
+    ar1 : array
         This array will be flattened if it is not already 1D.
-      - `return_index` : bool, optional
+    return_index : bool, optional
         If True, also return the indices against ar1 that result in the unique
         array.
 
-    :Returns:
-      - `unique` : array
+    Returns
+    -------
+    unique : array
         The unique values.
-      - `unique_indices` : int array, optional
+    unique_indices : int array, optional
         The indices of the unique values. Only provided if return_index is True.
 
-    :See also:
-      numpy.lib.arraysetops has a number of other functions for performing set
-      operations on arrays.
+    See Also
+    --------
+      numpy.lib.arraysetops : Module with a number of other functions
+                              for performing set operations on arrays.
+
     """
     ar = nm.asarray(ar1).flatten()
     if ar.size == 0:
@@ -110,66 +117,78 @@ def unique1d(ar1, return_index=False):
         flag = nm.concatenate( ([True], ar[1:] != ar[:-1]) )
         return ar[flag]
 
-def intersect1d( ar1, ar2 ):
+def intersect1d(ar1, ar2):
     """Intersection of 1D arrays with unique elements.
 
     Use unique1d() to generate arrays with only unique elements to use as inputs
     to this function. Alternatively, use intersect1d_nu() which will find the
     unique values for you.
 
-    :Parameters:
-      - `ar1` : array
-      - `ar2` : array
+    Parameters
+    ----------
+    ar1 : array
+    ar2 : array
+
+    Returns
+    -------
+    intersection : array
 
-    :Returns:
-      - `intersection` : array
+    See Also
+    --------
+    numpy.lib.arraysetops : Module with a number of other functions for
+                            performing set operations on arrays.
 
-    :See also:
-      numpy.lib.arraysetops has a number of other functions for performing set
-      operations on arrays.
     """
     aux = nm.concatenate((ar1,ar2))
     aux.sort()
     return aux[aux[1:] == aux[:-1]]
 
-def intersect1d_nu( ar1, ar2 ):
+def intersect1d_nu(ar1, ar2):
     """Intersection of 1D arrays with any elements.
 
     The input arrays do not have unique elements like intersect1d() requires.
 
-    :Parameters:
-      - `ar1` : array
-      - `ar2` : array
+    Parameters
+    ----------
+    ar1 : array
+    ar2 : array
 
-    :Returns:
-      - `intersection` : array
+    Returns
+    -------
+    intersection : array
+
+    See Also
+    --------
+    numpy.lib.arraysetops : Module with a number of other functions for
+                            performing set operations on arrays.
 
-    :See also:
-      numpy.lib.arraysetops has a number of other functions for performing set
-      operations on arrays.
     """
     # Might be faster than unique1d( intersect1d( ar1, ar2 ) )?
     aux = nm.concatenate((unique1d(ar1), unique1d(ar2)))
     aux.sort()
     return aux[aux[1:] == aux[:-1]]
 
-def setxor1d( ar1, ar2 ):
+def setxor1d(ar1, ar2):
     """Set exclusive-or of 1D arrays with unique elements.
 
     Use unique1d() to generate arrays with only unique elements to use as inputs
     to this function.
 
-    :Parameters:
-      - `ar1` : array
-      - `ar2` : array
+    Parameters
+    ----------
+    ar1 : array
+    ar2 : array
 
-    :Returns:
-      - `xor` : array
+    Returns
+    -------
+    xor : array
         The values that are only in one, but not both, of the input arrays.
 
-    :See also:
-      numpy.lib.arraysetops has a number of other functions for performing set
-      operations on arrays.
+    See Also
+    --------
+    numpy.lib.arraysetops : Module with a number of other functions for
+                            performing set operations on arrays.
+
     """
     aux = nm.concatenate((ar1, ar2))
     if aux.size == 0:
@@ -182,24 +201,28 @@ def setxor1d( ar1, ar2 ):
     flag2 = flag[1:] == flag[:-1]
     return aux[flag2]
 
-def setmember1d( ar1, ar2 ):
+def setmember1d(ar1, ar2):
     """Return a boolean array of shape of ar1 containing True where the elements
     of ar1 are in ar2 and False otherwise.
 
     Use unique1d() to generate arrays with only unique elements to use as inputs
     to this function.
 
-    :Parameters:
-      - `ar1` : array
-      - `ar2` : array
+    Parameters
+    ----------
+    ar1 : array
+    ar2 : array
 
-    :Returns:
-      - `mask` : bool array
+    Returns
+    -------
+    mask : bool array
         The values ar1[mask] are in ar2.
 
-    :See also:
-      numpy.lib.arraysetops has a number of other functions for performing set
-      operations on arrays.
+    See Also
+    --------
+    numpy.lib.arraysetops : Module with a number of other functions for
+                            performing set operations on arrays.
+
     """
     ar1 = nm.asarray( ar1 )
     ar2 = nm.asarray( ar2 )
@@ -225,42 +248,51 @@ def setmember1d( ar1, ar2 ):
 
     return flag[indx]
 
-def union1d( ar1, ar2 ):
-    """Union of 1D arrays with unique elements.
+def union1d(ar1, ar2):
+    """
+    Union of 1D arrays with unique elements.
 
     Use unique1d() to generate arrays with only unique elements to use as inputs
     to this function.
 
-    :Parameters:
-      - `ar1` : array
-      - `ar2` : array
+    Parameters
+    ----------
+    ar1 : array
+    ar2 : array
 
-    :Returns:
-      - `union` : array
+    Returns
+    -------
+    union : array
+
+    See also
+    --------
+    numpy.lib.arraysetops : Module with a number of other functions for
+                            performing set operations on arrays.
 
-    :See also:
-      numpy.lib.arraysetops has a number of other functions for performing set
-      operations on arrays.
     """
     return unique1d( nm.concatenate( (ar1, ar2) ) )
 
-def setdiff1d( ar1, ar2 ):
+def setdiff1d(ar1, ar2):
     """Set difference of 1D arrays with unique elements.
 
     Use unique1d() to generate arrays with only unique elements to use as inputs
     to this function.
 
-    :Parameters:
-      - `ar1` : array
-      - `ar2` : array
+    Parameters
+    ----------
+    ar1 : array
+    ar2 : array
 
-    :Returns:
-      - `difference` : array
+    Returns
+    -------
+    difference : array
         The values in ar1 that are not in ar2.
 
-    :See also:
-      numpy.lib.arraysetops has a number of other functions for performing set
-      operations on arrays.
+    See Also
+    --------
+    numpy.lib.arraysetops : Module with a number of other functions for
+                            performing set operations on arrays.
+
     """
     aux = setmember1d(ar1,ar2)
     if aux.size == 0:
diff --git a/numpy/lib/financial.py b/numpy/lib/financial.py
index 2a751281f..a3552ebc0 100644
--- a/numpy/lib/financial.py
+++ b/numpy/lib/financial.py
@@ -88,8 +88,8 @@ def pmt(rate, nper, pv, fv=0, when='end'):
     fact = np.where(rate==zer, nper+zer, (1+rate*when)*(temp-1)/rate+zer)
     return -(fv + pv*temp) / fact
 pmt.__doc__ += eqstr + """
-Example
--------
+Examples
+--------
 
 What would the monthly payment need to be to pay off a $200,000 loan in 15
   years at an annual interest rate of 7.5%?
@@ -116,8 +116,8 @@ def nper(rate, pmt, pv, fv=0, when='end'):
     zer = np.zeros(miter.shape)
     return np.where(rate==zer, A+zer, B+zer) + 0.0
 nper.__doc__ += eqstr + """
-Example
--------
+Examples
+--------
 
 If you only had $150 to spend as payment, how long would it take to pay-off
   a loan of $8,000 at 7% annual interest?
diff --git a/numpy/lib/function_base.py b/numpy/lib/function_base.py
index 8aed772d1..4236ca1bb 100644
--- a/numpy/lib/function_base.py
+++ b/numpy/lib/function_base.py
@@ -809,7 +809,16 @@ def interp(x, xp, fp, left=None, right=None):
 
 
 def angle(z, deg=0):
-    """Return the angle of the complex argument z.
+    """
+    Return the angle of the complex argument z.
+
+    Examples
+    --------
+    >>> numpy.angle(1+1j)          # in radians
+    0.78539816339744828
+    >>> numpy.angle(1+1j,deg=True) # in degrees
+    45.0
+
     """
     if deg:
         fact = 180/pi
@@ -889,11 +898,12 @@ if sys.hexversion < 0x2040000:
     from sets import Set as set
 
 def unique(x):
-    """Return sorted unique items from an array or sequence.
+    """
+    Return sorted unique items from an array or sequence.
 
     Examples
     --------
-    >>> unique([5,2,4,0,4,4,2,2,1])
+    >>> numpy.unique([5,2,4,0,4,4,2,2,1])
     array([0, 1, 2, 4, 5])
 
     """
@@ -1187,7 +1197,87 @@ def blackman(M):
     return 0.42-0.5*cos(2.0*pi*n/(M-1)) + 0.08*cos(4.0*pi*n/(M-1))
 
 def bartlett(M):
-    """bartlett(M) returns the M-point Bartlett window.
+    """
+    Return the Bartlett window.
+
+    The Bartlett window is very similar to a triangular window, except
+    that the end points are at zero.  It is often used in signal
+    processing for tapering a signal, without generating too much
+    ripple in the frequency domain.
+
+    Parameters
+    ----------
+    M : int
+        Number of points in the output window. If zero or less, an
+        empty array is returned.
+
+    Returns
+    -------
+    out : array
+        The triangular window, normalized to one (the value one
+        appears only if the number of samples is odd), with the first
+        and last samples equal to zero.
+
+    See Also
+    --------
+    blackman, hamming, hanning, kaiser
+
+    Notes
+    -----
+    The Bartlett window is defined as
+
+    .. math:: w(n) = \frac{2}{M-1} (\frac{M-1}{2} - |n - \frac{M-1}{2}|)
+
+    Most references to the Bartlett window come from the signal
+    processing literature, where it is used as one of many windowing
+    functions for smoothing values.  Note that convolution with this
+    window produces linear interpolation.  It is also known as an
+    apodization (which means"removing the foot", i.e. smoothing
+    discontinuities at the beginning and end of the sampled signal) or
+    tapering function.
+
+    References
+    ----------
+    .. [1] M.S. Bartlett, "Periodogram Analysis and Continuous Spectra",
+           Biometrika 37, 1-16, 1950.
+    .. [2] A.V. Oppenheim and R.W. Schafer, "Discrete-Time Signal
+           Processing", Prentice-Hall, 1999, pp. 468-471.
+    .. [3] Wikipedia, "Window function",
+           http://en.wikipedia.org/wiki/Window_function
+    .. [4] W.H. Press,  B.P. Flannery, S.A. Teukolsky, and W.T. Vetterling,
+           "Numerical Recipes", Cambridge University Press, 1986, page 429.
+
+    Examples
+    --------
+    >>> from numpy import bartlett
+    >>> bartlett(12)
+    array([ 0.        ,  0.18181818,  0.36363636,  0.54545455,  0.72727273,
+            0.90909091,  0.90909091,  0.72727273,  0.54545455,  0.36363636,
+            0.18181818,  0.        ])
+
+    #  Plot the window and the frequency response of it.
+    >>> from numpy import clip, log10, array, bartlett
+    >>> from scipy.fftpack import fft
+    >>> from matplotlib import pyplot as plt
+
+    >>> window = bartlett(51)
+    >>> plt.plot(window)
+    >>> plt.title("Bartlett window")
+    >>> plt.ylabel("Amplitude")
+    >>> plt.xlabel("Sample")
+    >>> plt.show()
+
+    >>> A = fft(window, 2048) / 25.5
+    >>> mag = abs(fftshift(A))
+    >>> freq = linspace(-0.5,0.5,len(A))
+    >>> response = 20*log10(mag)
+    >>> response = clip(response,-100,100)
+    >>> plt.plot(freq, response)
+    >>> plt.title("Frequency response of Bartlett window")
+    >>> plt.ylabel("Magnitude [dB]")
+    >>> plt.xlabel("Normalized frequency [cycles per sample]")
+    >>> plt.axis('tight'); plt.show()
+
     """
     if M < 1:
         return array([])
diff --git a/numpy/lib/index_tricks.py b/numpy/lib/index_tricks.py
index 2039d5b5e..4d82161bd 100644
--- a/numpy/lib/index_tricks.py
+++ b/numpy/lib/index_tricks.py
@@ -83,47 +83,47 @@ def ix_(*args):
     return tuple(out)
 
 class nd_grid(object):
-    """ Construct a "meshgrid" in N-dimensions.
-
-        grid = nd_grid() creates an instance which will return a mesh-grid
-        when indexed.  The dimension and number of the output arrays are equal
-        to the number of indexing dimensions.  If the step length is not a
-        complex number, then the stop is not inclusive.
-
-        However, if the step length is a COMPLEX NUMBER (e.g. 5j), then the
-        integer part of it's magnitude is interpreted as specifying the
-        number of points to create between the start and stop values, where
-        the stop value IS INCLUSIVE.
-
-        If instantiated with an argument of sparse=True, the mesh-grid is
-        open (or not fleshed out) so that only one-dimension of each returned
-        argument is greater than 1
-
-        Example:
-
-           >>> mgrid = nd_grid()
-           >>> mgrid[0:5,0:5]
-           array([[[0, 0, 0, 0, 0],
-                   [1, 1, 1, 1, 1],
-                   [2, 2, 2, 2, 2],
-                   [3, 3, 3, 3, 3],
-                   [4, 4, 4, 4, 4]],
-           <BLANKLINE>
-                  [[0, 1, 2, 3, 4],
-                   [0, 1, 2, 3, 4],
-                   [0, 1, 2, 3, 4],
-                   [0, 1, 2, 3, 4],
-                   [0, 1, 2, 3, 4]]])
-           >>> mgrid[-1:1:5j]
-           array([-1. , -0.5,  0. ,  0.5,  1. ])
-
-           >>> ogrid = nd_grid(sparse=True)
-           >>> ogrid[0:5,0:5]
-           [array([[0],
-                  [1],
-                  [2],
-                  [3],
-                  [4]]), array([[0, 1, 2, 3, 4]])]
+    """
+    Construct a multi-dimensional "meshgrid".
+
+    grid = nd_grid() creates an instance which will return a mesh-grid
+    when indexed.  The dimension and number of the output arrays are equal
+    to the number of indexing dimensions.  If the step length is not a
+    complex number, then the stop is not inclusive.
+
+    However, if the step length is a **complex number** (e.g. 5j), then the
+    integer part of it's magnitude is interpreted as specifying the
+    number of points to create between the start and stop values, where
+    the stop value **is inclusive**.
+
+    If instantiated with an argument of sparse=True, the mesh-grid is
+    open (or not fleshed out) so that only one-dimension of each returned
+    argument is greater than 1
+
+    Examples
+    --------
+    >>> mgrid = nd_grid()
+    >>> mgrid[0:5,0:5]
+    array([[[0, 0, 0, 0, 0],
+            [1, 1, 1, 1, 1],
+            [2, 2, 2, 2, 2],
+            [3, 3, 3, 3, 3],
+            [4, 4, 4, 4, 4]],
+    <BLANKLINE>
+           [[0, 1, 2, 3, 4],
+            [0, 1, 2, 3, 4],
+            [0, 1, 2, 3, 4],
+            [0, 1, 2, 3, 4],
+            [0, 1, 2, 3, 4]]])
+    >>> mgrid[-1:1:5j]
+    array([-1. , -0.5,  0. ,  0.5,  1. ])
+    >>> ogrid = nd_grid(sparse=True)
+    >>> ogrid[0:5,0:5]
+    [array([[0],
+            [1],
+            [2],
+            [3],
+            [4]]), array([[0, 1, 2, 3, 4]])]
 
     """
     def __init__(self, sparse=False):