DOC: fix build issues (with latex or newest sphinx)

1 files changed, 297 insertions, 295 deletions

diff --git a/numpy/doc/glossary.py b/numpy/doc/glossary.py
index dc7c75a0a..883100491 100644
--- a/numpy/doc/glossary.py
+++ b/numpy/doc/glossary.py
@@ -3,413 +3,415 @@
 Glossary
 ========
 
-along an axis
-    Axes are defined for arrays with more than one dimension.  A
-    2-dimensional array has two corresponding axes: the first running
-    vertically downwards across rows (axis 0), and the second running
-    horizontally across columns (axis 1).
+.. glossary::
 
-    Many operation can take place along one of these axes.  For example,
-    we can sum each row of an array, in which case we operate along
-    columns, or axis 1::
+   along an axis
+       Axes are defined for arrays with more than one dimension.  A
+       2-dimensional array has two corresponding axes: the first running
+       vertically downwards across rows (axis 0), and the second running
+       horizontally across columns (axis 1).
 
-      >>> x = np.arange(12).reshape((3,4))
+       Many operation can take place along one of these axes.  For example,
+       we can sum each row of an array, in which case we operate along
+       columns, or axis 1::
 
-      >>> x
-      array([[ 0,  1,  2,  3],
-             [ 4,  5,  6,  7],
-             [ 8,  9, 10, 11]])
+         >>> x = np.arange(12).reshape((3,4))
 
-      >>> x.sum(axis=1)
-      array([ 6, 22, 38])
+         >>> x
+         array([[ 0,  1,  2,  3],
+                [ 4,  5,  6,  7],
+                [ 8,  9, 10, 11]])
 
-array
-    A homogeneous container of numerical elements.  Each element in the
-    array occupies a fixed amount of memory (hence homogeneous), and
-    can be a numerical element of a single type (such as float, int
-    or complex) or a combination (such as ``(float, int, float)``).  Each
-    array has an associated data-type (or ``dtype``), which describes
-    the numerical type of its elements::
+         >>> x.sum(axis=1)
+         array([ 6, 22, 38])
 
-      >>> x = np.array([1, 2, 3], float)
+   array
+       A homogeneous container of numerical elements.  Each element in the
+       array occupies a fixed amount of memory (hence homogeneous), and
+       can be a numerical element of a single type (such as float, int
+       or complex) or a combination (such as ``(float, int, float)``).  Each
+       array has an associated data-type (or ``dtype``), which describes
+       the numerical type of its elements::
 
-      >>> x
-      array([ 1.,  2.,  3.])
+         >>> x = np.array([1, 2, 3], float)
 
-      >>> x.dtype # floating point number, 64 bits of memory per element
-      dtype('float64')
+         >>> x
+         array([ 1.,  2.,  3.])
 
+         >>> x.dtype # floating point number, 64 bits of memory per element
+         dtype('float64')
 
-      # More complicated data type: each array element is a combination of
-      # and integer and a floating point number
-      >>> np.array([(1, 2.0), (3, 4.0)], dtype=[('x', int), ('y', float)])
-      array([(1, 2.0), (3, 4.0)],
-            dtype=[('x', '<i4'), ('y', '<f8')])
 
-    Fast element-wise operations, called `ufuncs`_, operate on arrays.
+         # More complicated data type: each array element is a combination of
+         # and integer and a floating point number
+         >>> np.array([(1, 2.0), (3, 4.0)], dtype=[('x', int), ('y', float)])
+         array([(1, 2.0), (3, 4.0)],
+               dtype=[('x', '<i4'), ('y', '<f8')])
 
-array_like
-    Any sequence that can be interpreted as an ndarray.  This includes
-    nested lists, tuples, scalars and existing arrays.
+       Fast element-wise operations, called `ufuncs`_, operate on arrays.
 
-attribute
-    A property of an object that can be accessed using ``obj.attribute``,
-    e.g., ``shape`` is an attribute of an array::
+   array_like
+       Any sequence that can be interpreted as an ndarray.  This includes
+       nested lists, tuples, scalars and existing arrays.
 
-      >>> x = np.array([1, 2, 3])
-      >>> x.shape
-      (3,)
+   attribute
+       A property of an object that can be accessed using ``obj.attribute``,
+       e.g., ``shape`` is an attribute of an array::
 
-BLAS
-    `Basic Linear Algebra Subprograms <http://en.wikipedia.org/wiki/BLAS>`_
+         >>> x = np.array([1, 2, 3])
+         >>> x.shape
+         (3,)
 
-broadcast
-    NumPy can do operations on arrays whose shapes are mismatched::
+   BLAS
+       `Basic Linear Algebra Subprograms <http://en.wikipedia.org/wiki/BLAS>`_
 
-      >>> x = np.array([1, 2])
-      >>> y = np.array([[3], [4]])
+   broadcast
+       NumPy can do operations on arrays whose shapes are mismatched::
 
-      >>> x
-      array([1, 2])
+         >>> x = np.array([1, 2])
+         >>> y = np.array([[3], [4]])
 
-      >>> y
-      array([[3],
-             [4]])
+         >>> x
+         array([1, 2])
 
-      >>> x + y
-      array([[4, 5],
-             [5, 6]])
+         >>> y
+         array([[3],
+                [4]])
 
-    See `doc.broadcasting`_ for more information.
+         >>> x + y
+         array([[4, 5],
+                [5, 6]])
 
-C order
-    See `row-major`
+       See `doc.broadcasting`_ for more information.
 
-column-major
-    A way to represent items in a N-dimensional array in the 1-dimensional
-    computer memory. In column-major order, the leftmost index "varies the
-    fastest": for example the array::
+   C order
+       See `row-major`
 
-         [[1, 2, 3],
-          [4, 5, 6]]
+   column-major
+       A way to represent items in a N-dimensional array in the 1-dimensional
+       computer memory. In column-major order, the leftmost index "varies the
+       fastest": for example the array::
 
-    is represented in the column-major order as::
+            [[1, 2, 3],
+             [4, 5, 6]]
 
-        [1, 4, 2, 5, 3, 6]
+       is represented in the column-major order as::
 
-    Column-major order is also known as the Fortran order, as the Fortran
-    programming language uses it.
+           [1, 4, 2, 5, 3, 6]
 
-decorator
-    An operator that transforms a function.  For example, a ``log``
-    decorator may be defined to print debugging information upon
-    function execution::
+       Column-major order is also known as the Fortran order, as the Fortran
+       programming language uses it.
 
-      >>> def log(f):
-      ...     def new_logging_func(*args, **kwargs):
-      ...         print "Logging call with parameters:", args, kwargs
-      ...         return f(*args, **kwargs)
-      ...
-      ...     return new_logging_func
+   decorator
+       An operator that transforms a function.  For example, a ``log``
+       decorator may be defined to print debugging information upon
+       function execution::
 
-    Now, when we define a function, we can "decorate" it using ``log``::
+         >>> def log(f):
+         ...     def new_logging_func(*args, **kwargs):
+         ...         print "Logging call with parameters:", args, kwargs
+         ...         return f(*args, **kwargs)
+         ...
+         ...     return new_logging_func
 
-      >>> @log
-      ... def add(a, b):
-      ...     return a + b
+       Now, when we define a function, we can "decorate" it using ``log``::
 
-    Calling ``add`` then yields:
+         >>> @log
+         ... def add(a, b):
+         ...     return a + b
 
-    >>> add(1, 2)
-    Logging call with parameters: (1, 2) {}
-    3
+       Calling ``add`` then yields:
 
-dictionary
-    Resembling a language dictionary, which provides a mapping between
-    words and descriptions thereof, a Python dictionary is a mapping
-    between two objects::
+       >>> add(1, 2)
+       Logging call with parameters: (1, 2) {}
+       3
 
-      >>> x = {1: 'one', 'two': [1, 2]}
+   dictionary
+       Resembling a language dictionary, which provides a mapping between
+       words and descriptions thereof, a Python dictionary is a mapping
+       between two objects::
 
-    Here, `x` is a dictionary mapping keys to values, in this case
-    the integer 1 to the string "one", and the string "two" to
-    the list ``[1, 2]``.  The values may be accessed using their
-    corresponding keys::
+         >>> x = {1: 'one', 'two': [1, 2]}
 
-      >>> x[1]
-      'one'
+       Here, `x` is a dictionary mapping keys to values, in this case
+       the integer 1 to the string "one", and the string "two" to
+       the list ``[1, 2]``.  The values may be accessed using their
+       corresponding keys::
 
-      >>> x['two']
-      [1, 2]
+         >>> x[1]
+         'one'
 
-    Note that dictionaries are not stored in any specific order.  Also,
-    most mutable (see *immutable* below) objects, such as lists, may not
-    be used as keys.
+         >>> x['two']
+         [1, 2]
 
-    For more information on dictionaries, read the
-    `Python tutorial <http://docs.python.org/tut>`_.
+       Note that dictionaries are not stored in any specific order.  Also,
+       most mutable (see *immutable* below) objects, such as lists, may not
+       be used as keys.
 
-Fortran order
-    See `column-major`
+       For more information on dictionaries, read the
+       `Python tutorial <http://docs.python.org/tut>`_.
 
-flattened
-    Collapsed to a one-dimensional array. See `ndarray.flatten`_ for details.
+   Fortran order
+       See `column-major`
 
-immutable
-    An object that cannot be modified after execution is called
-    immutable.  Two common examples are strings and tuples.
+   flattened
+       Collapsed to a one-dimensional array. See `ndarray.flatten`_ for details.
 
-instance
-    A class definition gives the blueprint for constructing an object::
+   immutable
+       An object that cannot be modified after execution is called
+       immutable.  Two common examples are strings and tuples.
 
-      >>> class House(object):
-      ...     wall_colour = 'white'
+   instance
+       A class definition gives the blueprint for constructing an object::
 
-    Yet, we have to *build* a house before it exists::
+         >>> class House(object):
+         ...     wall_colour = 'white'
 
-      >>> h = House() # build a house
+       Yet, we have to *build* a house before it exists::
 
-    Now, ``h`` is called a ``House`` instance.  An instance is therefore
-    a specific realisation of a class.
+         >>> h = House() # build a house
 
-iterable
-    A sequence that allows "walking" (iterating) over items, typically
-    using a loop such as::
+       Now, ``h`` is called a ``House`` instance.  An instance is therefore
+       a specific realisation of a class.
 
-      >>> x = [1, 2, 3]
-      >>> [item**2 for item in x]
-      [1, 4, 9]
+   iterable
+       A sequence that allows "walking" (iterating) over items, typically
+       using a loop such as::
 
-    It is often used in combintion with ``enumerate``::
-      >>> keys = ['a','b','c']
-      >>> for n, k in enumerate(keys):
-      ...     print "Key %d: %s" % (n, k)
-      ...
-      Key 0: a
-      Key 1: b
-      Key 2: c
+         >>> x = [1, 2, 3]
+         >>> [item**2 for item in x]
+         [1, 4, 9]
 
-list
-    A Python container that can hold any number of objects or items.
-    The items do not have to be of the same type, and can even be
-    lists themselves::
+       It is often used in combintion with ``enumerate``::
+         >>> keys = ['a','b','c']
+         >>> for n, k in enumerate(keys):
+         ...     print "Key %d: %s" % (n, k)
+         ...
+         Key 0: a
+         Key 1: b
+         Key 2: c
 
-      >>> x = [2, 2.0, "two", [2, 2.0]]
+   list
+       A Python container that can hold any number of objects or items.
+       The items do not have to be of the same type, and can even be
+       lists themselves::
 
-    The list `x` contains 4 items, each which can be accessed individually::
+         >>> x = [2, 2.0, "two", [2, 2.0]]
 
-      >>> x[2] # the string 'two'
-      'two'
+       The list `x` contains 4 items, each which can be accessed individually::
 
-      >>> x[3] # a list, containing an integer 2 and a float 2.0
-      [2, 2.0]
+         >>> x[2] # the string 'two'
+         'two'
 
-    It is also possible to select more than one item at a time,
-    using *slicing*::
+         >>> x[3] # a list, containing an integer 2 and a float 2.0
+         [2, 2.0]
 
-      >>> x[0:2] # or, equivalently, x[:2]
-      [2, 2.0]
+       It is also possible to select more than one item at a time,
+       using *slicing*::
 
-    In code, arrays are often conveniently expressed as nested lists::
+         >>> x[0:2] # or, equivalently, x[:2]
+         [2, 2.0]
 
+       In code, arrays are often conveniently expressed as nested lists::
 
-      >>> np.array([[1, 2], [3, 4]])
-      array([[1, 2],
-             [3, 4]])
 
-    For more information, read the section on lists in the `Python
-    tutorial <http://docs.python.org/tut>`_.  For a mapping
-    type (key-value), see *dictionary*.
+         >>> np.array([[1, 2], [3, 4]])
+         array([[1, 2],
+                [3, 4]])
 
-mask
-    A boolean array, used to select only certain elements for an operation::
+       For more information, read the section on lists in the `Python
+       tutorial <http://docs.python.org/tut>`_.  For a mapping
+       type (key-value), see *dictionary*.
 
-      >>> x = np.arange(5)
-      >>> x
-      array([0, 1, 2, 3, 4])
+   mask
+       A boolean array, used to select only certain elements for an operation::
 
-      >>> mask = (x > 2)
-      >>> mask
-      array([False, False, False, True,  True], dtype=bool)
+         >>> x = np.arange(5)
+         >>> x
+         array([0, 1, 2, 3, 4])
 
-      >>> x[mask] = -1
-      >>> x
-      array([ 0,  1,  2,  -1, -1])
+         >>> mask = (x > 2)
+         >>> mask
+         array([False, False, False, True,  True], dtype=bool)
 
-masked array
-    Array that suppressed values indicated by a mask::
+         >>> x[mask] = -1
+         >>> x
+         array([ 0,  1,  2,  -1, -1])
 
-      >>> x = np.ma.masked_array([np.nan, 2, np.nan], [True, False, True])
-      >>> x
-      masked_array(data = [-- 2.0 --],
-                   mask = [ True False  True],
-             fill_value = 1e+20)
-      <BLANKLINE>
+   masked array
+       Array that suppressed values indicated by a mask::
 
-      >>> x + [1, 2, 3]
-      masked_array(data = [-- 4.0 --],
-                   mask = [ True False  True],
-             fill_value = 1e+20)
-      <BLANKLINE>
+         >>> x = np.ma.masked_array([np.nan, 2, np.nan], [True, False, True])
+         >>> x
+         masked_array(data = [-- 2.0 --],
+                      mask = [ True False  True],
+                fill_value = 1e+20)
+         <BLANKLINE>
 
+         >>> x + [1, 2, 3]
+         masked_array(data = [-- 4.0 --],
+                      mask = [ True False  True],
+                fill_value = 1e+20)
+         <BLANKLINE>
 
-    Masked arrays are often used when operating on arrays containing
-    missing or invalid entries.
 
-matrix
-    A 2-dimensional ndarray that preserves its two-dimensional nature
-    throughout operations.  It has certain special operations, such as ``*``
-    (matrix multiplication) and ``**`` (matrix power), defined::
+       Masked arrays are often used when operating on arrays containing
+       missing or invalid entries.
 
-      >>> x = np.mat([[1, 2], [3, 4]])
+   matrix
+       A 2-dimensional ndarray that preserves its two-dimensional nature
+       throughout operations.  It has certain special operations, such as ``*``
+       (matrix multiplication) and ``**`` (matrix power), defined::
 
-      >>> x
-      matrix([[1, 2],
-              [3, 4]])
+         >>> x = np.mat([[1, 2], [3, 4]])
 
-      >>> x**2
-      matrix([[ 7, 10],
-            [15, 22]])
+         >>> x
+         matrix([[1, 2],
+                 [3, 4]])
 
-method
-    A function associated with an object.  For example, each ndarray has a
-    method called ``repeat``::
+         >>> x**2
+         matrix([[ 7, 10],
+               [15, 22]])
 
-      >>> x = np.array([1, 2, 3])
+   method
+       A function associated with an object.  For example, each ndarray has a
+       method called ``repeat``::
 
-      >>> x.repeat(2)
-      array([1, 1, 2, 2, 3, 3])
+         >>> x = np.array([1, 2, 3])
 
-ndarray
-    See *array*.
+         >>> x.repeat(2)
+         array([1, 1, 2, 2, 3, 3])
 
-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.
+   ndarray
+       See *array*.
 
-row-major
-    A way to represent items in a N-dimensional array in the 1-dimensional
-    computer memory. In row-major order, the rightmost index "varies
-    the fastest": for example the array::
+   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.
 
-         [[1, 2, 3],
-          [4, 5, 6]]
+   row-major
+       A way to represent items in a N-dimensional array in the 1-dimensional
+       computer memory. In row-major order, the rightmost index "varies
+       the fastest": for example the array::
 
-    is represented in the row-major order as::
+            [[1, 2, 3],
+             [4, 5, 6]]
 
-        [1, 2, 3, 4, 5, 6]
+       is represented in the row-major order as::
 
-    Row-major order is also known as the C order, as the C programming
-    language uses it. New Numpy arrays are by default in row-major order.
+           [1, 2, 3, 4, 5, 6]
 
-self
-    Often seen in method signatures, ``self`` refers to the instance
-    of the associated class.  For example:
+       Row-major order is also known as the C order, as the C programming
+       language uses it. New Numpy arrays are by default in row-major order.
 
-      >>> class Paintbrush(object):
-      ...     color = 'blue'
-      ...
-      ...     def paint(self):
-      ...         print "Painting the city %s!" % self.color
-      ...
-      >>> p = Paintbrush()
-      >>> p.color = 'red'
-      >>> p.paint() # self refers to 'p'
-      Painting the city red!
+   self
+       Often seen in method signatures, ``self`` refers to the instance
+       of the associated class.  For example:
 
-slice
-    Used to select only certain elements from a sequence::
+         >>> class Paintbrush(object):
+         ...     color = 'blue'
+         ...
+         ...     def paint(self):
+         ...         print "Painting the city %s!" % self.color
+         ...
+         >>> p = Paintbrush()
+         >>> p.color = 'red'
+         >>> p.paint() # self refers to 'p'
+         Painting the city red!
 
-      >>> x = range(5)
-      >>> x
-      [0, 1, 2, 3, 4]
+   slice
+       Used to select only certain elements from a sequence::
 
-      >>> x[1:3] # slice from 1 to 3 (excluding 3 itself)
-      [1, 2]
+         >>> x = range(5)
+         >>> x
+         [0, 1, 2, 3, 4]
 
-      >>> x[1:5:2] # slice from 1 to 5, but skipping every second element
-      [1, 3]
+         >>> x[1:3] # slice from 1 to 3 (excluding 3 itself)
+         [1, 2]
 
-      >>> x[::-1] # slice a sequence in reverse
-      [4, 3, 2, 1, 0]
+         >>> x[1:5:2] # slice from 1 to 5, but skipping every second element
+         [1, 3]
 
-    Arrays may have more than one dimension, each which can be sliced
-    individually::
+         >>> x[::-1] # slice a sequence in reverse
+         [4, 3, 2, 1, 0]
 
-      >>> x = np.array([[1, 2], [3, 4]])
-      >>> x
-      array([[1, 2],
-             [3, 4]])
+       Arrays may have more than one dimension, each which can be sliced
+       individually::
 
-      >>> x[:, 1]
-      array([2, 4])
+         >>> x = np.array([[1, 2], [3, 4]])
+         >>> x
+         array([[1, 2],
+                [3, 4]])
 
-tuple
-    A sequence that may contain a variable number of types of any
-    kind.  A tuple is immutable, i.e., once constructed it cannot be
-    changed.  Similar to a list, it can be indexed and sliced::
+         >>> x[:, 1]
+         array([2, 4])
 
-      >>> x = (1, 'one', [1, 2])
+   tuple
+       A sequence that may contain a variable number of types of any
+       kind.  A tuple is immutable, i.e., once constructed it cannot be
+       changed.  Similar to a list, it can be indexed and sliced::
 
-      >>> x
-      (1, 'one', [1, 2])
+         >>> x = (1, 'one', [1, 2])
 
-      >>> x[0]
-      1
+         >>> x
+         (1, 'one', [1, 2])
 
-      >>> x[:2]
-      (1, 'one')
+         >>> x[0]
+         1
 
-    A useful concept is "tuple unpacking", which allows variables to
-    be assigned to the contents of a tuple::
+         >>> x[:2]
+         (1, 'one')
 
-      >>> x, y = (1, 2)
-      >>> x, y = 1, 2
+       A useful concept is "tuple unpacking", which allows variables to
+       be assigned to the contents of a tuple::
 
-    This is often used when a function returns multiple values:
+         >>> x, y = (1, 2)
+         >>> x, y = 1, 2
 
-      >>> def return_many():
-      ...     return 1, 'alpha', None
+       This is often used when a function returns multiple values:
 
-      >>> a, b, c = return_many()
-      >>> a, b, c
-      (1, 'alpha', None)
+         >>> def return_many():
+         ...     return 1, 'alpha', None
 
-      >>> a
-      1
-      >>> b
-      'alpha'
+         >>> a, b, c = return_many()
+         >>> a, b, c
+         (1, 'alpha', None)
 
-ufunc
-    Universal function.  A fast element-wise array operation.  Examples include
-    ``add``, ``sin`` and ``logical_or``.
+         >>> a
+         1
+         >>> b
+         'alpha'
 
-view
-    An array that does not own its data, but refers to another array's
-    data instead.  For example, we may create a view that only shows
-    every second element of another array::
+   ufunc
+       Universal function.  A fast element-wise array operation.  Examples include
+       ``add``, ``sin`` and ``logical_or``.
 
-      >>> x = np.arange(5)
-      >>> x
-      array([0, 1, 2, 3, 4])
+   view
+       An array that does not own its data, but refers to another array's
+       data instead.  For example, we may create a view that only shows
+       every second element of another array::
 
-      >>> y = x[::2]
-      >>> y
-      array([0, 2, 4])
+         >>> x = np.arange(5)
+         >>> x
+         array([0, 1, 2, 3, 4])
 
-      >>> x[0] = 3 # changing x changes y as well, since y is a view on x
-      >>> y
-      array([3, 2, 4])
+         >>> y = x[::2]
+         >>> y
+         array([0, 2, 4])
 
-wrapper
-    Python is a high-level (highly abstracted, or English-like) language.
-    This abstraction comes at a price in execution speed, and sometimes
-    it becomes necessary to use lower level languages to do fast
-    computations.  A wrapper is code that provides a bridge between
-    high and the low level languages, allowing, e.g., Python to execute
-    code written in C or Fortran.
+         >>> x[0] = 3 # changing x changes y as well, since y is a view on x
+         >>> y
+         array([3, 2, 4])
 
-    Examples include ctypes, SWIG and Cython (which wraps C and C++)
-    and f2py (which wraps Fortran).
+   wrapper
+       Python is a high-level (highly abstracted, or English-like) language.
+       This abstraction comes at a price in execution speed, and sometimes
+       it becomes necessary to use lower level languages to do fast
+       computations.  A wrapper is code that provides a bridge between
+       high and the low level languages, allowing, e.g., Python to execute
+       code written in C or Fortran.
+
+       Examples include ctypes, SWIG and Cython (which wraps C and C++)
+       and f2py (which wraps Fortran).
 
 """