more docstring updates from pydoc website (thanks to everyone who contributed!)

1 files changed, 120 insertions, 103 deletions

diff --git a/numpy/doc/indexing.py b/numpy/doc/indexing.py
index 282f35288..99def8889 100644
--- a/numpy/doc/indexing.py
+++ b/numpy/doc/indexing.py
@@ -14,10 +14,10 @@ found in related sections.
 Assignment vs referencing
 =========================
 
-Most of the following examples show the use of indexing when referencing
-data in an array. The examples work just as well when assigning to an
-array. See the section at the end for specific examples and explanations
-on how assignments work.
+Most of the following examples show the use of indexing when
+referencing data in an array. The examples work just as well
+when assigning to an array. See the section at the end for
+specific examples and explanations on how assignments work.
 
 Single element indexing
 =======================
@@ -48,39 +48,38 @@ than dimensions, one gets a subdimensional array. For example: ::
     >>> x[0]
     array([0, 1, 2, 3, 4])
 
-That is, each index specified selects the array corresponding to the rest
-of the dimensions selected. In the above example, choosing 0 means that
-remaining dimension of lenth 5 is being left unspecified, and that what
-is returned is an array of that dimensionality and size. It must be noted
-that the returned array is not a copy of the original, but points to the
-same values in memory as does the original array (a new view of the same
-data in other words, see xxx for details). In this case,
-the 1-D array at the first position (0) is returned. So using a single
-index on the returned array, results in a single element being returned.
-That is: ::
+That is, each index specified selects the array corresponding to the
+rest of the dimensions selected. In the above example, choosing 0
+means that remaining dimension of lenth 5 is being left unspecified,
+and that what is returned is an array of that dimensionality and size.
+It must be noted that the returned array is not a copy of the original,
+but points to the same values in memory as does the original array.
+In  this case, the 1-D array at the first position (0) is returned.
+So using a single index on the returned array, results in a single
+element being returned. That is: ::
 
     >>> x[0][2]
     2
 
-So note that ``x[0,2] = x[0][2]`` though the second case is more inefficient
-a new temporary array is created after the first index that is subsequently
-indexed by 2.
+So note that ``x[0,2] = x[0][2]`` though the second case is more
+inefficient a new temporary array is created after the first index
+that is subsequently indexed by 2.
 
-Note to those used to IDL or Fortran memory order as it relates to indexing.
-Numpy uses C-order indexing. That means that the last index usually (see
-xxx for exceptions) represents the most rapidly changing memory location,
-unlike Fortran or IDL, where the first index represents the most rapidly
-changing location in memory. This difference represents a great potential
-for confusion.
+Note to those used to IDL or Fortran memory order as it relates to
+indexing.  Numpy uses C-order indexing. That means that the last
+index usually represents the most rapidly changing memory location,
+unlike Fortran or IDL, where the first index represents the most
+rapidly changing location in memory. This difference represents a
+great potential for confusion.
 
 Other indexing options
 ======================
 
-It is possible to slice and stride arrays to extract arrays of the same
-number of dimensions, but of different sizes than the original. The slicing
-and striding works exactly the same way it does for lists and tuples except
-that they can be applied to multiple dimensions as well. A few
-examples illustrates best: ::
+It is possible to slice and stride arrays to extract arrays of the
+same number of dimensions, but of different sizes than the original.
+The slicing and striding works exactly the same way it does for lists
+and tuples except that they can be applied to multiple dimensions as
+well. A few examples illustrates best: ::
 
  >>> x = np.arange(10)
  >>> x[2:5]
@@ -95,35 +94,34 @@ examples illustrates best: ::
         [21, 24, 27]])
 
 Note that slices of arrays do not copy the internal array data but
-also produce new views of the original data (see xxx for more
-explanation of this issue).
+also produce new views of the original data.
 
 It is possible to index arrays with other arrays for the purposes of
-selecting lists of values out of arrays into new arrays. There are two
-different ways of accomplishing this. One uses one or more arrays of
-index values (see xxx for details). The other involves giving a boolean
-array of the proper shape to indicate the values to be selected.
-Index arrays are a very powerful tool that allow one to avoid looping
-over individual elements in arrays and thus greatly improve performance
-(see xxx for examples)
+selecting lists of values out of arrays into new arrays. There are
+two different ways of accomplishing this. One uses one or more arrays
+of index values. The other involves giving a boolean array of the proper
+shape to indicate the values to be selected. Index arrays are a very
+powerful tool that allow one to avoid looping over individual elements in
+arrays and thus greatly improve performance.
 
 It is possible to use special features to effectively increase the
 number of dimensions in an array through indexing so the resulting
 array aquires the shape needed for use in an expression or with a
-specific function. See xxx.
+specific function.
 
 Index arrays
 ============
 
-Numpy arrays may be indexed with other arrays (or any other sequence-like
-object that can be converted to an array, such as lists, with the exception
-of tuples; see the end of this document for why this is). The use of index
-arrays ranges from simple, straightforward cases to complex, hard-to-understand
-cases. For all cases of index arrays, what is returned is a copy of the
-original data, not a view as one gets for slices.
+Numpy arrays may be indexed with other arrays (or any other sequence-
+like object that can be converted to an array, such as lists, with the
+exception of tuples; see the end of this document for why this is). The
+use of index arrays ranges from simple, straightforward cases to
+complex, hard-to-understand cases. For all cases of index arrays, what
+is returned is a copy of the original data, not a view as one gets for
+slices.
 
-Index arrays must be of integer type. Each value in the array indicates which
-value in the array to use in place of the index. To illustrate: ::
+Index arrays must be of integer type. Each value in the array indicates
+which value in the array to use in place of the index. To illustrate: ::
 
  >>> x = np.arange(10,1,-1)
  >>> x
@@ -132,11 +130,12 @@ value in the array to use in place of the index. To illustrate: ::
  array([7, 7, 9, 2])
 
 
-The index array consisting of the values 3, 3, 1 and 8 correspondingly create
-an array of length 4 (same as the index array) where each index is replaced by
-the value the index array has in the array being indexed.
+The index array consisting of the values 3, 3, 1 and 8 correspondingly
+create an array of length 4 (same as the index array) where each index
+is replaced by the value the index array has in the array being indexed.
 
-Negative values are permitted and work as they do with single indices or slices: ::
+Negative values are permitted and work as they do with single indices
+or slices: ::
 
  >>> x[np.array([3,3,-3,8])]
  array([7, 7, 4, 2])
@@ -146,9 +145,10 @@ It is an error to have index values out of bounds: ::
  >>> x[np.array([3, 3, 20, 8])]
  <type 'exceptions.IndexError'>: index 20 out of bounds 0<=index<9
 
-Generally speaking, what is returned when index arrays are used is an array with
-the same shape as the index array, but with the type and values of the array being
-indexed. As an example, we can use a multidimensional index array instead: ::
+Generally speaking, what is returned when index arrays are used is
+an array with the same shape as the index array, but with the type
+and values of the array being indexed. As an example, we can use a
+multidimensional index array instead: ::
 
  >>> x[np.array([[1,1],[2,3]])]
  array([[9, 9],
@@ -157,77 +157,85 @@ indexed. As an example, we can use a multidimensional index array instead: ::
 Indexing Multi-dimensional arrays
 =================================
 
-Things become more complex when multidimensional arrays are indexed, particularly
-with multidimensional index arrays. These tend to be more unusal uses, but they
-are permitted, and they are useful for some problems. We'll  start with the
-simplest multidimensional case (using the array y from the previous examples): ::
+Things become more complex when multidimensional arrays are indexed,
+particularly with multidimensional index arrays. These tend to be
+more unusal uses, but theyare permitted, and they are useful for some
+problems. We'll  start with thesimplest multidimensional case (using
+the array y from the previous examples): ::
 
  >>> y[np.array([0,2,4]), np.array([0,1,2])]
  array([ 0, 15, 30])
 
-In this case, if the index arrays have a matching shape, and there is an index
-array for each dimension of the array being indexed, the resultant array has the
-same shape as the index arrays, and the values correspond to the index set for each
-position in the index arrays. In this example, the first index value is 0 for both
-index arrays, and thus the first value of the resultant array is y[0,0]. The next
-value is y[2,1], and the last is y[4,2].
+In this case, if the index arrays have a matching shape, and there is
+an index array for each dimension of the array being indexed, the
+resultant array has the same shape as the index arrays, and the values
+correspond to the index set for each position in the index arrays. In
+this example, the first index value is 0 for both index arrays, and
+thus the first value of the resultant array is y[0,0]. The next value
+is y[2,1], and the last is y[4,2].
 
-If the index arrays do not have the same shape, there is an attempt to broadcast
-them to the same shape. Broadcasting won't be discussed here but is discussed in
-detail in xxx. If they cannot be broadcast to the same shape, an exception is
-raised: ::
+If the index arrays do not have the same shape, there is an attempt to
+broadcast them to the same shape.  If they cannot be broadcast to the
+same shape, an exception is raised: ::
 
  >>> y[np.array([0,2,4]), np.array([0,1])]
- <type 'exceptions.ValueError'>: shape mismatch: objects cannot be broadcast to a single shape
+ <type 'exceptions.ValueError'>: shape mismatch: objects cannot be
+ broadcast to a single shape
 
-The broadcasting mechanism permits index arrays to be combined with scalars for
-other indices. The effect is that the scalar value is used for all the corresponding
-values of the index arrays: ::
+The broadcasting mechanism permits index arrays to be combined with
+scalars for other indices. The effect is that the scalar value is used
+for all the corresponding values of the index arrays: ::
 
  >>> y[np.array([0,2,4]), 1]
  array([ 1, 15, 29])
 
-Jumping to the next level of complexity, it is possible to only partially index an array
-with index arrays. It takes a bit of thought to understand what happens in such cases.
-For example if we just use one index array with y: ::
+Jumping to the next level of complexity, it is possible to only
+partially index an array with index arrays. It takes a bit of thought
+to understand what happens in such cases. For example if we just use
+one index array with y: ::
 
  >>> y[np.array([0,2,4])]
  array([[ 0,  1,  2,  3,  4,  5,  6],
         [14, 15, 16, 17, 18, 19, 20],
         [28, 29, 30, 31, 32, 33, 34]])
 
-What results is the construction of a new array where each value of the index array
-selects one row from the array being indexed and the resultant array has the resulting
-shape (size of row, number index elements).
+What results is the construction of a new array where each value of
+the index array selects one row from the array being indexed and the
+resultant array has the resulting shape (size of row, number index
+elements).
 
-An example of where this may be useful is for a color lookup table where we want to map
-the values of an image into RGB triples for display. The lookup table could have a shape
-(nlookup, 3). Indexing such an array with an image with shape (ny, nx) with dtype=np.uint8
-(or any integer type so long as values are with the bounds of the lookup table) will
-result in an array of shape (ny, nx, 3) where a triple of RGB values is associated with
-each pixel location.
+An example of where this may be useful is for a color lookup table
+where we want to map the values of an image into RGB triples for
+display. The lookup table could have a shape (nlookup, 3). Indexing
+such an array with an image with shape (ny, nx) with dtype=np.uint8
+(or any integer type so long as values are with the bounds of the
+lookup table) will result in an array of shape (ny, nx, 3) where a
+triple of RGB values is associated with each pixel location.
 
-In general, the shape of the resulant array will be the concatenation of the shape of
-the index array (or the shape that all the index arrays were broadcast to) with the
-shape of any unused dimensions (those not indexed) in the array being indexed.
+In general, the shape of the resulant array will be the concatenation
+of the shape of the index array (or the shape that all the index arrays
+were broadcast to) with the shape of any unused dimensions (those not
+indexed) in the array being indexed.
 
 Boolean or "mask" index arrays
 ==============================
 
-Boolean arrays used as indices are treated in a different manner entirely than index
-arrays. Boolean arrays must be of the same shape as the array being indexed, or
-broadcastable to the same shape. In the most straightforward case, the boolean array
-has the same shape: ::
+Boolean arrays used as indices are treated in a different manner
+entirely than index arrays. Boolean arrays must be of the same shape
+as the array being indexed, or broadcastable to the same shape. In the
+most straightforward case, the boolean array has the same shape: ::
 
  >>> b = y>20
  >>> y[b]
  array([21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34])
 
-The result is a 1-D array containing all the elements in the indexed array corresponding
-to all the true elements in the boolean array. As with index arrays, what is returned
-is a copy of the data, not a view as one gets with slices.
+The result is a 1-D array containing all the elements in the indexed
+array corresponding to all the true elements in the boolean array. As
+with index arrays, what is returned is a copy of the data, not a view
+as one gets with slices.
 
-With broadcasting, multidimesional arrays may be the result. For example: ::
+With broadcasting, multidimensional arrays may be the result. For
+example: ::
 
  >>> b[:,5] # use a 1-D boolean that broadcasts with y
  array([False, False, False,  True,  True], dtype=bool)
@@ -235,8 +243,8 @@ With broadcasting, multidimesional arrays may be the result. For example: ::
  array([[21, 22, 23, 24, 25, 26, 27],
         [28, 29, 30, 31, 32, 33, 34]])
 
-Here the 4th and 5th rows are selected from the indexed array and combined to make a
-2-D array.
+Here the 4th and 5th rows are selected from the indexed array and
+combined to make a 2-D array.
 
 Combining index arrays with slices
 ==================================
@@ -248,8 +256,9 @@ Index arrays may be combined with slices. For example: ::
         [15, 16],
         [29, 30]])
 
-In effect, the slice is converted to an index array np.array([[1,2]]) (shape (1,2)) that is
-broadcast with the index array to produce a resultant array of shape (3,2).
+In effect, the slice is converted to an index array
+np.array([[1,2]]) (shape (1,2)) that is broadcast with the index array
+to produce a resultant array of shape (3,2).
 
 Likewise, slicing can be combined with broadcasted boolean indices: ::
 
@@ -322,7 +331,8 @@ exceptions (assigning complex to floats or ints): ::
  >>> x[1]
  1
  >>> x[1] = 1.2j
- <type 'exceptions.TypeError'>: can't convert complex to long; use long(abs(z))
+ <type 'exceptions.TypeError'>: can't convert complex to long; use
+ long(abs(z))
 
 
 Unlike some of the references (such as array and mask indices)
@@ -331,7 +341,12 @@ assignments are always made to the original data in the array
 actions may not work as one may naively expect. This particular
 example is often surprising to people: ::
 
+ >>> x = np.arange(0, 50, 10)
+ >>> x
+ array([ 0, 10, 20, 30, 40])
  >>> x[np.array([1, 1, 3, 1])] += 1
+ >>> x
+ array([ 0, 11, 20, 31, 40])
 
 Where people expect that the 1st location will be incremented by 3.
 In fact, it will only be incremented by 1. The reason is because
@@ -367,7 +382,8 @@ in Python. For example: ::
  >>> z[indices]
  array([39, 40])
 
-Likewise, ellipsis can be specified by code by using the Ellipsis object: ::
+Likewise, ellipsis can be specified by code by using the Ellipsis
+object: ::
 
  >>> indices = (1, Ellipsis, 1) # same as [1,...,1]
  >>> z[indices]
@@ -376,10 +392,11 @@ Likewise, ellipsis can be specified by code by using the Ellipsis object: ::
         [46, 49, 52]])
 
 For this reason it is possible to use the output from the np.where()
-function directly as an index since it always returns a tuple of index arrays.
+function directly as an index since it always returns a tuple of index
+arrays.
 
-Because the special treatment of tuples, they are not automatically converted
-to an array as a list would be. As an example: ::
+Because the special treatment of tuples, they are not automatically
+converted to an array as a list would be. As an example: ::
 
  >>> z[[1,1,1,1]] # produces a large array
  array([[[[27, 28, 29],