second set of checkins from doc editor

doc/source/reference/arrays.classes.rst

@@ -230,8 +230,8 @@ Character arrays (:mod:`numpy.char`)
 .. note::
    The chararray module exists for backwards compatibility with
    Numarray, it is not recommended for new development. If one needs
-   arrays of strings, use arrays of `dtype` `object_`, `string_` or
-   `unicode_`.
+   arrays of strings, use arrays of `dtype` `object_`, `str` or
+   `unicode`.
 
 These are enhanced arrays of either :class:`string_` type or
 :class:`unicode_` type.  These arrays inherit from the
@@ -242,7 +242,7 @@ character type. In addition, the :class:`chararray` has all of the
 standard :class:`string <str>` (and :class:`unicode`) methods,
 executing them on an element-by-element basis. Perhaps the easiest way
 to create a chararray is to use :meth:`self.view(chararray)
-<ndarray.view>` where *self* is an ndarray of string or unicode
+<ndarray.view>` where *self* is an ndarray of str or unicode
 data-type. However, a chararray can also be created using the
 :meth:`numpy.chararray` constructor, or via the
 :func:`numpy.char.array <core.defchararray.array>` function:
@@ -253,7 +253,7 @@ data-type. However, a chararray can also be created using the
    chararray
    core.defchararray.array
 
-Another difference with the standard ndarray of string data-type is
+Another difference with the standard ndarray of str data-type is
 that the chararray inherits the feature introduced by Numarray that
 white-space at the end of any element in the array will be ignored on
 item retrieval and comparison operations.

doc/source/reference/arrays.ndarray.rst

@@ -120,6 +120,8 @@ strided scheme, and correspond to the strides:
 
 .. index:: single-segment, contiguous, non-contiguous
 
+where :math:`d_j` = `self.itemsize * self.shape[j]`.
+
 Both the C and Fortran orders are :term:`contiguous`, *i.e.,*
 :term:`single-segment`, memory layouts, in which every part of the
 memory block can be accessed by some combination of the indices.
@@ -231,7 +233,7 @@ Array methods
 
 An :class:`ndarray` object has many methods which operate on or with
 the array in some fashion, typically returning an array result. These
-methods are briefly explained below. (Each method's doc string has a
+methods are briefly explained below. (Each method's docstring has a
 more complete description.)
 
 For the following methods there are also corresponding functions in
@@ -317,11 +319,45 @@ Many of these methods take an argument named *axis*. In such cases,
 - If *axis* is *None* (the default), the array is treated as a 1-D
   array and the operation is performed over the entire array. This
   behavior is also the default if self is a 0-dimensional array or
-  array scalar.
+  array scalar. (An array scalar is an instance of the types/classes
+  float32, float64, etc., whereas a 0-dimensional array is an ndarray
+  instance containing precisely one array scalar.)
 
 - If *axis* is an integer, then the operation is done over the given axis
   (for each 1-D subarray that can be created along the given axis).
 
+.. admonition:: Example of the *axis* argument
+
+   A 3-dimensional array of size 3 x 3 x 3, summed over each of its
+   three axes
+
+   >>> x
+   array([[[ 0,  1,  2],
+           [ 3,  4,  5],
+           [ 6,  7,  8]],
+          [[ 9, 10, 11],
+           [12, 13, 14],
+           [15, 16, 17]],
+          [[18, 19, 20],
+           [21, 22, 23],
+           [24, 25, 26]]])
+   >>> x.sum(axis=0)
+   array([[27, 30, 33],
+          [36, 39, 42],
+          [45, 48, 51]])
+   >>> # for sum, axis is the first keyword, so we may omit it,
+   >>> # specifying only its value
+   >>> x.sum(0), x.sum(1), x.sum(2)
+   (array([[27, 30, 33],
+           [36, 39, 42],
+           [45, 48, 51]]),
+    array([[ 9, 12, 15],
+           [36, 39, 42],
+           [63, 66, 69]]),
+    array([[ 3, 12, 21],
+           [30, 39, 48],
+           [57, 66, 75]]))
+
 The parameter *dtype* specifies the data type over which a reduction
 operation (like summing) should take place. The default reduce data
 type is the same as the data type of *self*. To avoid overflow, it can
@@ -333,7 +369,6 @@ argument must be an :class:`ndarray` and have the same number of
 elements. It can have a different data type in which case casting will
 be performed.
 
-
 .. autosummary::
    :toctree: generated/
 

doc/source/reference/c-api.array.rst

@@ -2372,7 +2372,7 @@ Other conversions
     signed and unsigned integers, floating point numbers, and
     complex-floating point numbers are recognized and converted. Other
     values of gentype are returned. This function can be used to
-    convert, for example, the string'f4' to :cdata:`NPY_FLOAT32`.
+    convert, for example, the string 'f4' to :cdata:`NPY_FLOAT32`.
 
 
 Miscellaneous

doc/source/reference/distutils.rst

@@ -6,7 +6,7 @@ Packaging (:mod:`numpy.distutils`)
 
 NumPy provides enhanced distutils functionality to make it easier to
 build and install sub-packages, auto-generate code, and extension
-modules that use Fortran-compiled libraries. To use features of numpy
+modules that use Fortran-compiled libraries. To use features of NumPy
 distutils, use the :func:`setup <core.setup>` command from
 :mod:`numpy.distutils.core`. A useful :class:`Configuration
 <misc_util.Configuration>` class is also provided in
@@ -33,7 +33,6 @@ misc_util
 
    Configuration
    get_numpy_include_dirs
-   get_numarray_include_dirs
    dict_append
    appendpath
    allpath
@@ -128,22 +127,22 @@ Other modules
 Building Installable C libraries
 ================================
 
-Conventional C libraries (installed through add_library) are not installed, and
+Conventional C libraries (installed through `add_library`) are not installed, and
 are just used during the build (they are statically linked).  An installable C
 library is a pure C library, which does not depend on the python C runtime, and
-is installed such as it may be used by third-party packages. To build and
-install the C library, you just use the method add_installed_library instead of
-add_library, which takes the same arguments except for an additional
-install_dir argument::
+is installed such that it may be used by third-party packages. To build and
+install the C library, you just use the method `add_installed_library` instead of
+`add_library`, which takes the same arguments except for an additional
+``install_dir`` argument::
 
   >>> config.add_installed_library('foo', sources=['foo.c'], install_dir='lib')
 
 npy-pkg-config files
 --------------------
 
 To make the necessary build options available to third parties, you could use
-the npy-pkg-config mechanism implemented in numpy.distutils. This mechanism is
-based on an .ini file which contains all the options. A .ini file is very
+the `npy-pkg-config` mechanism implemented in `numpy.distutils`. This mechanism is
+based on a .ini file which contains all the options. A .ini file is very
 similar to .pc files as used by the pkg-config unix utility::
 
   [meta]
@@ -162,7 +161,7 @@ similar to .pc files as used by the pkg-config unix utility::
 
 Generally, the file needs to be generated during the build, since it needs some
 information known at build time only (e.g. prefix). This is mostly automatic if
-one uses the Configuration method add_npy_pkg_config. Assuming we have a
+one uses the `Configuration` method `add_npy_pkg_config`. Assuming we have a
 template file foo.ini.in as follows::
 
   [meta]
@@ -186,22 +185,23 @@ and the following code in setup.py::
   >>> config.add_npy_pkg_config('foo.ini.in', 'lib', subst_dict=subst)
 
 This will install the file foo.ini into the directory package_dir/lib, and the
-foo.ini file will be generated from foo.ini.in, where each @version@ will be
-replaced by subst_dict['version']. The dictionary has an additional prefix
+foo.ini file will be generated from foo.ini.in, where each ``@version@`` will be
+replaced by ``subst_dict['version']``. The dictionary has an additional prefix
 substitution rule automatically added, which contains the install prefix (since
 this is not easy to get from setup.py).  npy-pkg-config files can also be
 installed at the same location as used for numpy, using the path returned from
-get_npy_pkg_dir function.
+`get_npy_pkg_dir` function.
 
 Reusing a C library from another package
 ----------------------------------------
 
-Info are easily retrieved from the get_info function in numpy.distutils.misc_util::
+Info are easily retrieved from the `get_info` function in
+`numpy.distutils.misc_util`::
 
   >>> info = get_info('npymath')
   >>> config.add_extension('foo', sources=['foo.c'], extra_info=**info)
 
-An additional list of paths to look for .ini files can be given to get_info.
+An additional list of paths to look for .ini files can be given to `get_info`.
 
 Conversion of ``.src`` files
 ============================

doc/source/reference/routines.math.rst

@@ -19,6 +19,8 @@ Trigonometric functions
    degrees
    radians
    unwrap
+   deg2rad
+   rad2deg
 
 Hyperbolic functions
 --------------------
@@ -43,6 +45,7 @@ Rounding
    fix
    floor
    ceil
+   trunc
 
 Sums, products, differences
 ---------------------------
@@ -67,10 +70,13 @@ Exponents and logarithms
 
    exp
    expm1
+   exp2
    log
    log10
    log2
    log1p
+   logaddexp
+   logaddexp2
 
 Other special functions
 -----------------------
@@ -86,6 +92,7 @@ Floating point routines
    :toctree: generated/
 
    signbit
+   copysign
    frexp
    ldexp
 

doc/source/reference/ufuncs.rst

@@ -313,7 +313,7 @@ possess. None of the attributes can be set.
 ============  =================================================================
 **__doc__**   A docstring for each ufunc. The first part of the docstring is
               dynamically generated from the number of outputs, the name, and
-              the number of inputs. The second part of the doc string is
+              the number of inputs. The second part of the docstring is
               provided at creation time and stored with the ufunc.
 
 **__name__**  The name of the ufunc.

doc/source/user/index.rst

@@ -1,20 +1,23 @@
 .. _user:
 
 ################
-Numpy User Guide
+NumPy User Guide
 ################
 
-This guide explains how to make use of different features
-of Numpy. For a detailed documentation about different functions
-and classes, see :ref:`reference`.
+This guide is intended as an introductory overview of NumPy and
+explains how to install and make use of the most important features of
+NumPy. For detailed reference documentation of the functions and
+classes contained in the package, see the :ref:`reference`.
 
 .. warning::
 
-   This "User Guide" is still very much work in progress; the material
-   is not organized, and many aspects of Numpy are not covered.
+   This "User Guide" is still a work in progress; some of the material
+   is not organized, and several aspects of NumPy are not yet covered
+   in sufficient detail. However, we are continually working to
+   improve the documentation.
 
-   More documentation for Numpy can be found on the
-   `scipy.org <http://www.scipy.org/Documentation>`__ website.
+   More documentation for NumPy can be found on the `numpy.org
+   <http://www.numpy.org>`__ website.
 
 .. toctree::
    :maxdepth: 2