Merge docstrings from wiki.

3 files changed, 85 insertions, 25 deletions

diff --git a/numpy/__init__.py b/numpy/__init__.py
index 00494fb37..c304f542d 100644
--- a/numpy/__init__.py
+++ b/numpy/__init__.py
@@ -1,14 +1,65 @@
 """
 NumPy
-==========
+=====
+
 Provides
-   1) An array object of arbitrary homogeneous items
-   2) Fast mathematical operations over arrays
-   3) Linear Algebra, Fourier Transforms, Random Number Generation
+  1. An array object of arbitrary homogeneous items
+  2. Fast mathematical operations over arrays
+  3. Linear Algebra, Fourier Transforms, Random Number Generation
+
+Documentation is available in the docstrings and at http://www.scipy.org
+
+Available subpackages
+---------------------
+core
+    Defines a multi-dimensional array and useful procedures
+    for Numerical computation.
+lib
+    Basic functions used by several sub-packages and useful
+    to have in the main name-space.
+random
+    Core Random Tools
+linalg
+    Core Linear Algebra Tools
+fft
+    Core FFT routines
+testing
+    Numpy testing tools
+
+The following sub-packages must be explicitly imported:
+
+f2py
+    Fortran to Python Interface Generator.
+distutils
+    Enhancements to distutils with support for
+    Fortran compilers support and more.
+
+
+Global symbols from subpackages
+-------------------------------
+========  =================================
+core      all (use numpy.* not numpy.core.*)
+lib       all (use numpy.* not numpy.lib.*)
+testing   NumpyTest
+========  =================================
+
+
+Utility tools
+-------------
 
-Documentation is available in the docstrings and at
+test
+    Run numpy unittests
+pkgload
+    Load numpy packages
+show_config
+    Show numpy build configuration
+dual
+    Overwrite certain functions with high-performance Scipy tools
+matlib
+    Make everything matrices.
+__version__
+    Numpy version string
 
-http://www.scipy.org
 """
 
 # We first need to detect if we're being called as part of the numpy setup
diff --git a/numpy/core/defmatrix.py b/numpy/core/defmatrix.py
index 0c18dfb91..ba085bfad 100644
--- a/numpy/core/defmatrix.py
+++ b/numpy/core/defmatrix.py
@@ -125,19 +125,20 @@ def matrix_power(M,n):
 
 
 class matrix(N.ndarray):
-    """mat = matrix(data, dtype=None, copy=True)
+    """
+    mat = matrix(data, dtype=None, copy=True)
 
     Returns a matrix from an array-like object, or a string of
     data.  A matrix is a specialized 2-d array that retains
-    it's 2-d nature through operations and where '*' means matrix
+    its 2-d nature through operations and where '*' means matrix
     multiplication and '**' means matrix power.
 
     Parameters
     ----------
     data : array-like or string
        If data is a string, then interpret the string as a matrix
-         with commas or spaces separating columns and semicolons
-         separating rows.
+       with commas or spaces separating columns and semicolons
+       separating rows.
        If data is array-like than convert the array to a matrix.
     dtype : data-type
        Anything that can be interpreted as a NumPy datatype.
@@ -152,6 +153,7 @@ class matrix(N.ndarray):
     >>> print a
     [[1 2]
      [3 4]]
+
     """
     __array_priority__ = 10.0
     def __new__(subtype, data, dtype=None, copy=True):
@@ -532,18 +534,22 @@ def _from_string(str,gdict,ldict):
 
 
 def bmat(obj, ldict=None, gdict=None):
-    """Build a matrix object from string, nested sequence, or array.
+    """
+    Build a matrix object from string, nested sequence, or array.
 
-    Example
+    Examples
     --------
-    F = bmat('A, B; C, D')
-    F = bmat([[A,B],[C,D]])
-    F = bmat(r_[c_[A,B],c_[C,D]])
+    >>> F = bmat('A, B; C, D')
+    >>> F = bmat([[A,B],[C,D]])
+    >>> F = bmat(r_[c_[A,B],c_[C,D]])
+
+    All of these produce the same matrix::
 
-    all produce the same Matrix Object    [ A  B ]
-                                          [ C  D ]
+        [ A  B ]
+        [ C  D ]
 
     if A, B, C, and D are appropriately shaped 2-d arrays.
+
     """
     if isinstance(obj, str):
         if gdict is None:
diff --git a/numpy/lib/io.py b/numpy/lib/io.py
index 709a2445a..dce462ac7 100644
--- a/numpy/lib/io.py
+++ b/numpy/lib/io.py
@@ -428,7 +428,9 @@ def savetxt(fname, X, fmt='%.18e',delimiter=' '):
 
 import re
 def fromregex(file, regexp, dtype):
-    """Construct an array from a text file, using regular-expressions parsing.
+    """
+    Construct a record array from a text file, using
+    regular-expressions parsing.
 
     Array is constructed from all matches of the regular expression
     in the file. Groups in the regular expression are converted to fields.
@@ -436,19 +438,20 @@ def fromregex(file, regexp, dtype):
     Parameters
     ----------
     file : str or file
-        File name or file object to read
+        File name or file object to read.
     regexp : str or regexp
-        Regular expression to use to parse the file
+        Regular expression used to parse the file.
+        Groups in the regular expression correspond to fields in the dtype.
     dtype : dtype or dtype list
         Dtype for the structured array
 
-    Example
-    -------
-    >>> import numpy as np
+    Examples
+    --------
     >>> f = open('test.dat', 'w')
-    >>> f.write("1312 foo\n1534  bar\n 444   qux")
+    >>> f.write("1312 foo\\n1534  bar\\n444   qux")
     >>> f.close()
-    >>> np.fromregex('test.dat', r"(\d+)\s+(...)", [('num', np.int64), ('key', 'S3')])
+    >>> np.fromregex('test.dat', r"(\\d+)\\s+(...)",
+    ...              [('num', np.int64), ('key', 'S3')])
     array([(1312L, 'foo'), (1534L, 'bar'), (444L, 'qux')],
           dtype=[('num', '<i8'), ('key', '|S3')])