DOC: Fix docstring warnings in documetation generation.

Most of these fixes involve putting blank lines around

.. versionadded:: x.x.x

and

.. deprecated:: x.x.x

Some of the examples were also fixed.

12 files changed, 116 insertions, 66 deletions

diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py
index be32d0cfa..a6d7dc32e 100644
--- a/numpy/add_newdocs.py
+++ b/numpy/add_newdocs.py
@@ -790,14 +790,16 @@ add_newdoc('numpy.core.multiarray', 'empty_like',
         The shape and data-type of `a` define these same attributes of the
         returned array.
     dtype : data-type, optional
-        .. versionadded:: 1.6.0
         Overrides the data type of the result.
-    order : {'C', 'F', 'A', or 'K'}, optional
+
         .. versionadded:: 1.6.0
+    order : {'C', 'F', 'A', or 'K'}, optional
         Overrides the memory layout of the result. 'C' means C-order,
         'F' means F-order, 'A' means 'F' if ``a`` is Fortran contiguous,
         'C' otherwise. 'K' means match the layout of ``a`` as closely
         as possible.
+
+        .. versionadded:: 1.6.0
     subok : bool, optional.
         If True, then the newly created array will use the sub-class
         type of 'a', otherwise it will be a base-class array. Defaults
@@ -1703,6 +1705,7 @@ add_newdoc('numpy.core.multiarray', 'promote_types',
     Notes
     -----
     .. versionadded:: 1.6.0
+
     Starting in NumPy 1.9, promote_types function now returns a valid string
     length when given an integer or float dtype as one argument and a string
     dtype as another argument. Previously it always returned the input string
@@ -5039,10 +5042,10 @@ add_newdoc('numpy.core.multiarray', 'bincount',
     weights : array_like, optional
         Weights, array of the same shape as `x`.
     minlength : int, optional
-        .. versionadded:: 1.6.0
-
         A minimum number of bins for the output array.
 
+        .. versionadded:: 1.6.0
+
     Returns
     -------
     out : ndarray of ints
@@ -5164,10 +5167,11 @@ add_newdoc('numpy.core.multiarray', 'unravel_index',
     dims : tuple of ints
         The shape of the array to use for unraveling ``indices``.
     order : {'C', 'F'}, optional
-        .. versionadded:: 1.6.0
         Determines whether the indices should be viewed as indexing in
         row-major (C-style) or column-major (Fortran-style) order.
 
+        .. versionadded:: 1.6.0
+
     Returns
     -------
     unraveled_coords : tuple of ndarray
diff --git a/numpy/core/defchararray.py b/numpy/core/defchararray.py
index 92ea8209c..ead11e8d8 100644
--- a/numpy/core/defchararray.py
+++ b/numpy/core/defchararray.py
@@ -2652,7 +2652,7 @@ def asarray(obj, itemsize=None, unicode=None, order=None):
          end when comparing values
 
       3) vectorized string operations are provided as methods
-         (e.g. `str.endswith`) and infix operators (e.g. +, *, %)
+         (e.g. `str.endswith`) and infix operators (e.g. ``+``, ``*``,``%``)
 
     Parameters
     ----------
diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py
index b6a28ec9b..10626fe9f 100644
--- a/numpy/core/fromnumeric.py
+++ b/numpy/core/fromnumeric.py
@@ -1049,10 +1049,11 @@ def searchsorted(a, v, side='left', sorter=None):
         If 'right', return the last such index.  If there is no suitable
         index, return either 0 or N (where N is the length of `a`).
     sorter : 1-D array_like, optional
-        .. versionadded:: 1.7.0
         Optional array of integer indices that sort array a into ascending
         order. They are typically the result of argsort.
 
+        .. versionadded:: 1.7.0
+
     Returns
     -------
     indices : array of ints
diff --git a/numpy/core/numeric.py b/numpy/core/numeric.py
index f29b750f6..f7b0f49fa 100644
--- a/numpy/core/numeric.py
+++ b/numpy/core/numeric.py
@@ -89,14 +89,16 @@ def zeros_like(a, dtype=None, order='K', subok=True):
         The shape and data-type of `a` define these same attributes of
         the returned array.
     dtype : data-type, optional
-        .. versionadded:: 1.6.0
         Overrides the data type of the result.
-    order : {'C', 'F', 'A', or 'K'}, optional
+
         .. versionadded:: 1.6.0
+    order : {'C', 'F', 'A', or 'K'}, optional
         Overrides the memory layout of the result. 'C' means C-order,
         'F' means F-order, 'A' means 'F' if `a` is Fortran contiguous,
         'C' otherwise. 'K' means match the layout of `a` as closely
         as possible.
+
+        .. versionadded:: 1.6.0
     subok : bool, optional.
         If True, then the newly created array will use the sub-class
         type of 'a', otherwise it will be a base-class array. Defaults
@@ -195,14 +197,16 @@ def ones_like(a, dtype=None, order='K', subok=True):
         The shape and data-type of `a` define these same attributes of
         the returned array.
     dtype : data-type, optional
-        .. versionadded:: 1.6.0
         Overrides the data type of the result.
-    order : {'C', 'F', 'A', or 'K'}, optional
+
         .. versionadded:: 1.6.0
+    order : {'C', 'F', 'A', or 'K'}, optional
         Overrides the memory layout of the result. 'C' means C-order,
         'F' means F-order, 'A' means 'F' if `a` is Fortran contiguous,
         'C' otherwise. 'K' means match the layout of `a` as closely
         as possible.
+
+        .. versionadded:: 1.6.0
     subok : bool, optional.
         If True, then the newly created array will use the sub-class
         type of 'a', otherwise it will be a base-class array. Defaults
@@ -1016,9 +1020,10 @@ def outer(a, b, out=None):
         Second input vector.  Input is flattened if
         not already 1-dimensional.
     out : (M, N) ndarray, optional
-        .. versionadded:: 1.9.0
         A location where the result is stored
 
+        .. versionadded:: 1.9.0
+
     Returns
     -------
     out : (M, N) ndarray
@@ -1494,6 +1499,7 @@ def cross(a, b, axisa=-1, axisb=-1, axisc=-1, axis=None):
     Notes
     -----
     .. versionadded:: 1.9.0
+
     Supports full broadcasting of the inputs.
 
     Examples
@@ -2222,10 +2228,11 @@ def allclose(a, b, rtol=1.e-5, atol=1.e-8, equal_nan=False):
     atol : float
         The absolute tolerance parameter (see Notes).
     equal_nan : bool
-        .. versionadded:: 1.10.0
         Whether to compare NaN's as equal.  If True, NaN's in `a` will be
         considered equal to NaN's in `b` in the output array.
 
+        .. versionadded:: 1.10.0
+
     Returns
     -------
     allclose : bool
diff --git a/numpy/distutils/exec_command.py b/numpy/distutils/exec_command.py
index f4b6f5928..f0382accc 100644
--- a/numpy/distutils/exec_command.py
+++ b/numpy/distutils/exec_command.py
@@ -9,6 +9,7 @@ values may be different by a factor). In addition, exec_command
 takes keyword arguments for (re-)defining environment variables.
 
 Provides functions:
+
   exec_command  --- execute command in a specified directory and
                     in the modified environment.
   find_executable --- locate a command using info from environment
@@ -21,28 +22,33 @@ Created: 11 January 2003
 Requires: Python 2.x
 
 Succesfully tested on:
-  os.name | sys.platform | comments
-  --------+--------------+----------
-  posix   | linux2       | Debian (sid) Linux, Python 2.1.3+, 2.2.3+, 2.3.3
-                           PyCrust 0.9.3, Idle 1.0.2
-  posix   | linux2       | Red Hat 9 Linux, Python 2.1.3, 2.2.2, 2.3.2
-  posix   | sunos5       | SunOS 5.9, Python 2.2, 2.3.2
-  posix   | darwin       | Darwin 7.2.0, Python 2.3
-  nt      | win32        | Windows Me
-                           Python 2.3(EE), Idle 1.0, PyCrust 0.7.2
-                           Python 2.1.1 Idle 0.8
-  nt      | win32        | Windows 98, Python 2.1.1. Idle 0.8
-  nt      | win32        | Cygwin 98-4.10, Python 2.1.1(MSC) - echo tests
-                           fail i.e. redefining environment variables may
-                           not work. FIXED: don't use cygwin echo!
-                           Comment: also `cmd /c echo` will not work
-                           but redefining environment variables do work.
-  posix   | cygwin       | Cygwin 98-4.10, Python 2.3.3(cygming special)
-  nt      | win32        | Windows XP, Python 2.3.3
+
+========  ============  =================================================
+os.name   sys.platform  comments
+========  ============  =================================================
+posix     linux2        Debian (sid) Linux, Python 2.1.3+, 2.2.3+, 2.3.3
+                        PyCrust 0.9.3, Idle 1.0.2
+posix     linux2        Red Hat 9 Linux, Python 2.1.3, 2.2.2, 2.3.2
+posix     sunos5        SunOS 5.9, Python 2.2, 2.3.2
+posix     darwin        Darwin 7.2.0, Python 2.3
+nt        win32         Windows Me
+                        Python 2.3(EE), Idle 1.0, PyCrust 0.7.2
+                        Python 2.1.1 Idle 0.8
+nt        win32         Windows 98, Python 2.1.1. Idle 0.8
+nt        win32         Cygwin 98-4.10, Python 2.1.1(MSC) - echo tests
+                        fail i.e. redefining environment variables may
+                        not work. FIXED: don't use cygwin echo!
+                        Comment: also `cmd /c echo` will not work
+                        but redefining environment variables do work.
+posix     cygwin        Cygwin 98-4.10, Python 2.3.3(cygming special)
+nt        win32         Windows XP, Python 2.3.3
+========  ============  =================================================
 
 Known bugs:
-- Tests, that send messages to stderr, fail when executed from MSYS prompt
+
+* Tests, that send messages to stderr, fail when executed from MSYS prompt
   because the messages are lost at some point.
+
 """
 from __future__ import division, absolute_import, print_function
 
@@ -148,21 +154,33 @@ def _supports_fileno(stream):
     else:
         return False
 
-def exec_command( command,
-                  execute_in='', use_shell=None, use_tee = None,
-                  _with_python = 1,
-                  **env ):
-    """ Return (status,output) of executed command.
-
-    command is a concatenated string of executable and arguments.
-    The output contains both stdout and stderr messages.
-    The following special keyword arguments can be used:
-      use_shell - execute `sh -c command`
-      use_tee   - pipe the output of command through tee
-      execute_in - before run command `cd execute_in` and after `cd -`.
-
+def exec_command(command, execute_in='', use_shell=None, use_tee=None,
+                 _with_python = 1, **env ):
+    """
+    Return (status,output) of executed command.
+
+    Parameters
+    ----------
+    command : str
+        A concatenated string of executable and arguments.
+    execute_in : str
+        Before running command ``cd execute_in`` and after ``cd -``.
+    use_shell : {bool, None}, optional
+        If True, execute ``sh -c command``. Default None (True)
+    use_tee : {bool, None}, optional
+        If True use tee. Default None (True)
+
+
+    Returns
+    -------
+    res : str
+        Both stdout and stderr messages.
+
+    Notes
+    -----
     On NT, DOS systems the returned status is correct for external commands.
     Wild cards will not work for non-posix systems or when use_shell=0.
+
     """
     log.debug('exec_command(%r,%s)' % (command,\
          ','.join(['%s=%r'%kv for kv in env.items()])))
diff --git a/numpy/doc/glossary.py b/numpy/doc/glossary.py
index f856a742b..9dacd1cb5 100644
--- a/numpy/doc/glossary.py
+++ b/numpy/doc/glossary.py
@@ -264,7 +264,6 @@ Glossary
        (matrix multiplication) and ``**`` (matrix power), defined::
 
          >>> x = np.mat([[1, 2], [3, 4]])
-
          >>> x
          matrix([[1, 2],
                  [3, 4]])
@@ -278,18 +277,17 @@ Glossary
        method called ``repeat``::
 
          >>> x = np.array([1, 2, 3])
-
          >>> x.repeat(2)
          array([1, 1, 2, 2, 3, 3])
 
    ndarray
        See *array*.
-    
+
    record array
        An `ndarray`_ with `structured data type`_ which has been subclassed as
        np.recarray and whose dtype is of type np.record, making the
        fields of its data type to be accessible by attribute.
-       
+
    reference
        If ``a`` is a reference to ``b``, then ``(a is b) == True``.  Therefore,
        ``a`` and ``b`` are different names for the same Python object.
@@ -360,7 +358,6 @@ Glossary
        changed.  Similar to a list, it can be indexed and sliced::
 
          >>> x = (1, 'one', [1, 2])
-
          >>> x
          (1, 'one', [1, 2])
 
diff --git a/numpy/lib/arraysetops.py b/numpy/lib/arraysetops.py
index 3dd97aecf..17dfa7567 100644
--- a/numpy/lib/arraysetops.py
+++ b/numpy/lib/arraysetops.py
@@ -114,10 +114,11 @@ def unique(ar, return_index=False, return_inverse=False, return_counts=False):
         If True, also return the indices of the unique array that can be used
         to reconstruct `ar`.
     return_counts : bool, optional
-        .. versionadded:: 1.9.0
         If True, also return the number of times each unique value comes up
         in `ar`.
 
+        .. versionadded:: 1.9.0
+
     Returns
     -------
     unique : ndarray
@@ -129,10 +130,11 @@ def unique(ar, return_index=False, return_inverse=False, return_counts=False):
         The indices to reconstruct the (flattened) original array from the
         unique array. Only provided if `return_inverse` is True.
     unique_counts : ndarray, optional
-        .. versionadded:: 1.9.0
         The number of times each of the unique values comes up in the
         original array. Only provided if `return_counts` is True.
 
+        .. versionadded:: 1.9.0
+
     See Also
     --------
     numpy.lib.arraysetops : Module with a number of other functions for
diff --git a/numpy/lib/function_base.py b/numpy/lib/function_base.py
index d4db4dab1..38a96707f 100644
--- a/numpy/lib/function_base.py
+++ b/numpy/lib/function_base.py
@@ -1146,11 +1146,12 @@ def interp(x, xp, fp, left=None, right=None, period=None):
         Value to return for `x > xp[-1]`, default is `fp[-1]`.
 
     period : None or float, optional
-        .. versionadded:: 1.10.0
         A period for the x-coordinates. This parameter allows the proper
         interpolation of angular x-coordinates. Parameters `left` and `right`
         are ignored if `period` is specified.
 
+        .. versionadded:: 1.10.0
+
     Returns
     -------
     y : float or ndarray
@@ -1863,23 +1864,26 @@ def cov(m, y=None, rowvar=1, bias=0, ddof=None, fweights=None, aweights=None):
         normalization is by ``N``. These values can be overridden by using the
         keyword ``ddof`` in numpy versions >= 1.5.
     ddof : int, optional
-        .. versionadded:: 1.5
         If not ``None`` the default value implied by `bias` is overridden.
         Note that ``ddof=1`` will return the unbiased estimate, even if both
         `fweights` and `aweights` are specified, and ``ddof=0`` will return
         the simple average. See the notes for the details. The default value
         is ``None``.
+
+        .. versionadded:: 1.5
     fweights : array_like, int, optional
-        .. versionadded:: 1.10
         1-D array of integer freguency weights; the number of times each
         observation vector should be repeated.
-    aweights : array_like, optional
+
         .. versionadded:: 1.10
+    aweights : array_like, optional
         1-D array of observation vector weights. These relative weights are
         typically large for observations considered "important" and smaller for
         observations considered less "important". If ``ddof=0`` the array of
         weights can be used to assign probabilities to observation vectors.
 
+        .. versionadded:: 1.10
+
     Returns
     -------
     out : ndarray
@@ -2054,12 +2058,14 @@ def corrcoef(x, y=None, rowvar=1, bias=np._NoValue, ddof=np._NoValue):
         is transposed: each column represents a variable, while the rows
         contain observations.
     bias : _NoValue, optional
-        .. deprecated:: 1.10.0
         Has no affect, do not use.
-    ddof : _NoValue, optional
+
         .. deprecated:: 1.10.0
+    ddof : _NoValue, optional
         Has no affect, do not use.
 
+        .. deprecated:: 1.10.0
+
     Returns
     -------
     R : ndarray
diff --git a/numpy/lib/npyio.py b/numpy/lib/npyio.py
index 271c6ab49..86d757630 100644
--- a/numpy/lib/npyio.py
+++ b/numpy/lib/npyio.py
@@ -745,6 +745,7 @@ def loadtxt(fname, dtype=float, comments='#', delimiter=None,
     lines with missing values.
 
     .. versionadded:: 1.10.0
+
     The strings produced by the Python float.hex method can be used as
     input for floats.
 
diff --git a/numpy/linalg/linalg.py b/numpy/linalg/linalg.py
index 07a7a0d42..cf5b314ac 100644
--- a/numpy/linalg/linalg.py
+++ b/numpy/linalg/linalg.py
@@ -238,8 +238,8 @@ def tensorsolve(a, b, axes=None):
         Coefficient tensor, of shape ``b.shape + Q``. `Q`, a tuple, equals
         the shape of that sub-tensor of `a` consisting of the appropriate
         number of its rightmost indices, and must be such that
-       ``prod(Q) == prod(b.shape)`` (in which sense `a` is said to be
-       'square').
+        ``prod(Q) == prod(b.shape)`` (in which sense `a` is said to be
+        'square').
     b : array_like
         Right-hand tensor, which can be of any shape.
     axes : tuple of ints, optional
@@ -321,6 +321,7 @@ def solve(a, b):
     -----
 
     .. versionadded:: 1.8.0
+
     Broadcasting rules apply, see the `numpy.linalg` documentation for
     details.
 
@@ -480,6 +481,7 @@ def inv(a):
     -----
 
     .. versionadded:: 1.8.0
+
     Broadcasting rules apply, see the `numpy.linalg` documentation for
     details.
 
@@ -559,6 +561,7 @@ def cholesky(a):
     -----
 
     .. versionadded:: 1.8.0
+
     Broadcasting rules apply, see the `numpy.linalg` documentation for
     details.
 
@@ -860,6 +863,7 @@ def eigvals(a):
     -----
 
     .. versionadded:: 1.8.0
+
     Broadcasting rules apply, see the `numpy.linalg` documentation for
     details.
 
@@ -950,6 +954,7 @@ def eigvalsh(a, UPLO='L'):
     -----
 
     .. versionadded:: 1.8.0
+
     Broadcasting rules apply, see the `numpy.linalg` documentation for
     details.
 
@@ -1035,6 +1040,7 @@ def eig(a):
     -----
 
     .. versionadded:: 1.8.0
+
     Broadcasting rules apply, see the `numpy.linalg` documentation for
     details.
 
@@ -1173,6 +1179,7 @@ def eigh(a, UPLO='L'):
     -----
 
     .. versionadded:: 1.8.0
+
     Broadcasting rules apply, see the `numpy.linalg` documentation for
     details.
 
@@ -1282,6 +1289,7 @@ def svd(a, full_matrices=1, compute_uv=1):
     -----
 
     .. versionadded:: 1.8.0
+
     Broadcasting rules apply, see the `numpy.linalg` documentation for
     details.
 
@@ -1653,10 +1661,12 @@ def slogdet(a):
     -----
 
     .. versionadded:: 1.8.0
+
     Broadcasting rules apply, see the `numpy.linalg` documentation for
     details.
 
     .. versionadded:: 1.6.0.
+
     The determinant is computed via LU factorization using the LAPACK
     routine z/dgetrf.
 
@@ -1732,6 +1742,7 @@ def det(a):
     -----
 
     .. versionadded:: 1.8.0
+
     Broadcasting rules apply, see the `numpy.linalg` documentation for
     details.
 
@@ -1983,11 +1994,12 @@ def norm(x, ord=None, axis=None, keepdims=False):
         are computed.  If `axis` is None then either a vector norm (when `x`
         is 1-D) or a matrix norm (when `x` is 2-D) is returned.
     keepdims : bool, optional
-        .. versionadded:: 1.10.0
         If this is set to True, the axes which are normed over are left in the
         result as dimensions with size one.  With this option the result will
         broadcast correctly against the original `x`.
 
+        .. versionadded:: 1.10.0
+
     Returns
     -------
     n : float or ndarray
diff --git a/numpy/ma/extras.py b/numpy/ma/extras.py
index 2f8114563..bd593e65f 100644
--- a/numpy/ma/extras.py
+++ b/numpy/ma/extras.py
@@ -1371,11 +1371,11 @@ def cov(x, y=None, rowvar=True, bias=False, allow_masked=True, ddof=None):
         in `x`, the corresponding value is masked in `y`.
         If False, raises a `ValueError` exception when some values are missing.
     ddof : {None, int}, optional
-        .. versionadded:: 1.5
         If not ``None`` normalization is by ``(N - ddof)``, where ``N`` is
         the number of observations; this overrides the value implied by
         ``bias``. The default value is ``None``.
 
+        .. versionadded:: 1.5
 
     Raises
     ------
@@ -1430,17 +1430,19 @@ def corrcoef(x, y=None, rowvar=True, bias=np._NoValue, allow_masked=True,
         is transposed: each column represents a variable, while the rows
         contain observations.
     bias : _NoValue, optional
-        .. deprecated:: 1.10.0
         Has no affect, do not use.
+
+        .. deprecated:: 1.10.0
     allow_masked : bool, optional
         If True, masked values are propagated pair-wise: if a value is masked
         in `x`, the corresponding value is masked in `y`.
         If False, raises an exception.  Because `bias` is deprecated, this
         argument needs to be treated as keyword only to avoid a warning.
     ddof : _NoValue, optional
-        .. deprecated:: 1.10.0
         Has no affect, do not use.
 
+        .. deprecated:: 1.10.0
+
     See Also
     --------
     numpy.corrcoef : Equivalent function in top-level NumPy module.
diff --git a/numpy/random/mtrand/mtrand.pyx b/numpy/random/mtrand/mtrand.pyx
index 5c949d07b..8345ac97e 100644
--- a/numpy/random/mtrand/mtrand.pyx
+++ b/numpy/random/mtrand/mtrand.pyx
@@ -2430,7 +2430,7 @@ cdef class RandomState:
         For a one-sided t-test, how far out in the distribution does the t
         statistic appear?
 
-        >>> >>> np.sum(s<t) / float(len(s))
+        >>> np.sum(s<t) / float(len(s))
         0.0090699999999999999  #random
 
         So the p-value is about 0.009, which says the null hypothesis has a
@@ -3285,7 +3285,7 @@ cdef class RandomState:
         ...    b.append(np.product(a))
 
         >>> b = np.array(b) / np.min(b) # scale values to be positive
-        >>> count, bins, ignored = plt.hist(b, 100, normed=True, align='center')
+        >>> count, bins, ignored = plt.hist(b, 100, normed=True, align='mid')
         >>> sigma = np.std(np.log(b))
         >>> mu = np.mean(np.log(b))