Merge pull request #1918 from nouiz/doc

doc/library/index.txt

@@ -22,6 +22,7 @@ Types and Ops that you can use to build and compile expression graphs.
    gof/index
    scan
    sandbox/index
+   typed_list
 
 There are also some top-level imports that you might find more convenient:
 

doc/library/sparse/index.txt

@@ -119,16 +119,18 @@ List of Implemented Operations
 ==============================
 
 - Moving from and to sparse
-    - :class:`DenseFromSparse <theano.sparse.basic.DenseFromSparse>` and ``dense_from_sparse``.
+    - :func:`dense_from_sparse <theano.sparse.basic.dense_from_sparse>`.
       Both grads are implemented. Structured by default.
-    - :class:`SparseFromDense <theano.sparse.basic.SparseFromDense>` and ``csr_from_dense``, ``csc_from_dense``.
+    - :func:`csr_from_dense <theano.sparse.basic.csr_from_dense>`,
+      :func:`csc_from_dense <theano.sparse.basic.csc_from_dense>`.
       The grad implemented is structured.
-    - Theano SparseVariable object have a method ``toarray()`` that is the same as ``dense_from_sparse``.
+    - Theano SparseVariable object have a method ``toarray()`` that is the same as
+      :func:`dense_from_sparse <theano.sparse.basic.dense_from_sparse>`.
 
 - Construction of Sparses and their Properties
     - :class:`CSM <theano.sparse.basic.CSM>` and ``CSC``, ``CSR`` to construct a matrix.
       The grad implemented is regular.
-    - :class:`CSMProperties <theano.sparse.basic.CSMProperties>` and ``csm_properties(x)``
+    - :func:`csm_properties <theano.sparse.basic.csm_properties>`.
       to get the properties of a sparse matrix.
       The grad implemented is regular.
     - csm_indices(x), csm_indptr(x), csm_data(x) and csm_shape(x) or x.shape.
@@ -136,22 +138,22 @@ List of Implemented Operations
       The grad implemented is regular.
     - :func:`sp_zeros_like <theano.sparse.basic.sp_zeros_like>`.
       The grad implemented is regular.
-    - :class:`SquareDiagonal <theano.sparse.basic.SquareDiagonal>` and ``square_diagonal``.
+    - :func:`square_diagonal <theano.sparse.basic.square_diagonal>`.
       The grad implemented is regular.
-    - :class:`ConstructSparseFromList <theano.sparse.basic.ConstructSparseFromList>` and ``construct_sparse_from_list``.
+    - :func:`construct_sparse_from_list <theano.sparse.basic.construct_sparse_from_list>`.
       The grad implemented is regular.
 
 - Cast
-    - :class:`Cast <theano.sparse.basic.Cast>` with ``bcast``, ``wcast``, ``icast``, ``lcast``,
+    - :func:`cast <theano.sparse.basic.cast>` with ``bcast``, ``wcast``, ``icast``, ``lcast``,
       ``fcast``, ``dcast``, ``ccast``, and ``zcast``.
       The grad implemented is regular.
 
 - Transpose
-    - :class:`Transpose <theano.sparse.basic.Transpose>` and ``transpose``.
+    - :func:`transpose <theano.sparse.basic.transpose>`.
       The grad implemented is regular.
 
 - Basic Arithmetic
-    - :class:`Neg <theano.sparse.basic.Neg>`.
+    - :func:`neg <theano.sparse.basic.neg>`.
       The grad implemented is regular.
     - :func:`eq <theano.sparse.basic.eq>`.
     - :func:`neq <theano.sparse.basic.neq>`.
@@ -201,15 +203,13 @@ List of Implemented Operations
     - ``sqrt``
 
 - Dot Product
-    - :class:`Dot <theano.sparse.basic.Dot>` and
-      :func:`dot <theano.sparse.basic.dot>`.
+    - :func:`dot <theano.sparse.basic.dot>`.
 
         - One of the inputs must be sparse, the other sparse or dense.
         - The grad implemented is regular.
         - No C code for perform and no C code for grad.
         - Returns a dense for perform and a dense for grad.
-    - :class:`StructuredDot <theano.sparse.basic.StructuredDot>`
-      and :func:`structured_dot <theano.sparse.basic.structured_dot>`.
+    - :func:`structured_dot <theano.sparse.basic.structured_dot>`.
 
         - The first input is sparse, the second can be sparse or dense.
         - The grad implemented is structured.
@@ -218,8 +218,7 @@ List of Implemented Operations
           dense one if one of the inputs is dense.
         - Returns a sparse grad for sparse inputs and dense grad for
           dense inputs.
-    - :class:`TrueDot <theano.sparse.basic.TrueDot>` and
-      :func:`true_dot <theano.sparse.basic.true_dot>`.
+    - :func:`true_dot <theano.sparse.basic.true_dot>`.
 
         - The first input is sparse, the second can be sparse or dense.
         - The grad implemented is regular.
@@ -229,19 +228,18 @@ List of Implemented Operations
           default a dense for dense inputs. The parameter
           ``grad_preserves_dense`` can be set to False to return a
           sparse grad for dense inputs.
-    - :class:`SamplingDot <theano.sparse.basic.SamplingDot>` and
-      ``sampling_dot``.
+    - :func:`sampling_dot <theano.sparse.basic.sampling_dot>`.
 
         - Both inputs must be dense.
         - The grad implemented is structured for `p`.
         - Sample of the dot and sample of the gradient.
         - C code for perform but not for grad.
         - Returns sparse for perform and grad.
-    - :class:`Usmm <theano.sparse.basic.Usmm>` and ``usmm``.
+    - :func:`usmm <theano.sparse.basic.usmm>`.
 
         - You *shouldn't* insert this op yourself!
            - There is an optimization that transform a
-             :class:`Dot <theano.sparse.basic.Dot>` to ``Usmm`` when possible.
+             :func:`dot <theano.sparse.basic.dot>` to ``Usmm`` when possible.
 
         - This op is the equivalent of gemm for sparse dot.
         - There is no grad implemented for this op.
@@ -256,13 +254,13 @@ List of Implemented Operations
     - Sparse variables don't support [M, N:O] and [M:N, O] as we don't
       support sparse vectors and returning a sparse matrix would break
       the numpy interface.  Use [M:M+1, N:O] and [M:N, O:O+1] instead.
-    - :class:`Diag <theano.sparse.basic.Diag>` and ``diag``.
+    - :func:`diag <theano.sparse.basic.diag>`.
       The grad implemented is regular.
 
 - Concatenation
-    - :class:`HStack <theano.sparse.basic.HStack>` and ``hstack``.
+    - :func:`hstack <theano.sparse.basic.hstack>`.
       The grad implemented is regular.
-    - :class:`VStack <theano.sparse.basic.VStack>` and ``vstack``.
+    - :func:`vstack <theano.sparse.basic.vstack>`.
       The grad implemented is regular.
 
 - Probability
@@ -276,8 +274,8 @@ List of Implemented Operations
 - Internal Representation
     `They all have a regular grad implemented.`
 
-    - :class:`EnsureSortedIndices <theano.sparse.basic.EnsureSortedIndices>` and ``ensure_sorted_indices``
-    - :class:`Remove0 <theano.sparse.basic.Remove0>` and ``remove0``
+    - :func:`ensure_sorted_indices <theano.sparse.basic.ensure_sorted_indices>`.
+    - :func:`remove0 <theano.sparse.basic.remove0>`.
     - :func:`clean <theano.sparse.basic.clean>` to resort indices and remove zeros
 
 - To help testing

doc/library/typed_list.txt

+.. _libdoc_typed_list:
+
+===============================
+:mod:`typed_list` -- Typed List
+===============================
+
+.. note::
+
+    This is not in the released version 0.6.0, but will be in the next release (0.7 or 0.6.1).
+
+This is a type that represents a list in Theano. All elements must have
+the same Theano type. Here is an example::
+
+    import theano.typed_list
+
+    tl = theano.typed_list.TypedListType(theano.tensor.fvector)()
+    v = theano.tensor.fvector()
+    o = theano.typed_list.append(tl, v)
+    f = theano.function([tl, v], o)
+    print f([[1, 2, 3], [4, 5]], [2])
+    #[array([ 1.,  2.,  3.], dtype=float32), array([ 4.,  5.], dtype=float32), array([ 2.], dtype=float32)]
+
+A second example with Scan. Scan doesn't yet have direct support of
+TypedList, so you can only use it as non_sequences (not in sequences or
+as outputs).::
+
+    import theano.typed_list
+
+    a = theano.typed_list.TypedListType(theano.tensor.fvector)()
+    l = theano.typed_list.length(a)
+    s, _ = theano.scan(fn=lambda i, tl: tl[i].sum(),
+                       non_sequences=[a],
+                       sequences=[theano.tensor.arange(l, dtype='int64')])
+
+    f = theano.function([a], s)
+    f([[1, 2, 3], [4, 5]])
+    #array([ 6.,  9.], dtype=float32)
+
+.. automodule:: theano.typed_list.basic
+    :members:

theano/typed_list/basic.py

@@ -50,9 +50,7 @@ TypedListType.Variable = TypedListVariable
 
 
 class GetItem(Op):
-    """
-    get specified slice of a typed list
-    """
+    # See doc in instance of this Op or function after this class definition.
     def __eq__(self, other):
         return type(self) == type(other)
 
@@ -100,13 +98,16 @@ class GetItem(Op):
         return (1,)
 
 getitem = GetItem()
+"""
+Get specified slice of a typed list.
 
+:param x: type type list.
+:param index: the index of the value to return from `x`.
+"""
 
-class Append(Op):
-    """
-    #append an element at the end of another list
-    """
 
+class Append(Op):
+    # See doc in instance of this Op after the class definition.
     def __init__(self, inplace=False):
         self.inplace = inplace
         if self.inplace:
@@ -159,13 +160,16 @@ class Append(Op):
         return (1,)
 
 append = Append()
+"""
+Append an element at the end of another list.
+
+:param x: the base typed list.
+:param y: the element to append to `x`.
+"""
 
 
 class Extend(Op):
-    """
-    append all element of a list at the end of another list
-    """
-
+    # See doc in instance of this Op after the class definition.
     def __init__(self, inplace=False):
         self.inplace = inplace
         if self.inplace:
@@ -222,10 +226,16 @@ class Extend(Op):
         return (1,)
 
 extend = Extend()
+"""
+Append all element of a list at the end of another list.
 
+:param x: The typed list to extend.
+:param toAppend: The typed list that will be added at the end of `x`.
+"""
 
-class Insert(Op):
 
+class Insert(Op):
+    # See doc in instance of this Op after the class definition.
     def __init__(self, inplace=False):
         self.inplace = inplace
         if self.inplace:
@@ -283,10 +293,17 @@ class Insert(Op):
         return (1,)
 
 insert = Insert()
+"""
+Insert an element at an index in a typed list.
 
+:param x: the typed list to modified.
+:param index: the index where to put the new element in `x`.
+:param toInsert: The new element to insert.
+"""
 
-class Remove(Op):
 
+class Remove(Op):
+    # See doc in instance of this Op after the class definition.
     def __init__(self, inplace=False):
         self.inplace = inplace
         if self.inplace:
@@ -324,10 +341,21 @@ class Remove(Op):
         return self.__class__.__name__
 
 remove = Remove()
+"""Remove an element from a typed list.
 
+:param x: the typed list to be changed.
+:param toRemove: an element to be removed from the typed list.
+    We only remove the first instance.
 
-class Reverse(Op):
+:note: Python implementation of remove doesn't work when we want to
+    remove an ndarray from a list. This implementation works in that
+    case.
 
+"""
+
+
+class Reverse(Op):
+    # See doc in instance of this Op after the class definition.
     def __init__(self, inplace=False):
         self.inplace = inplace
         if self.inplace:
@@ -380,10 +408,15 @@ class Reverse(Op):
         return (1,)
 
 reverse = Reverse()
+"""
+Reverse the order of a typed list.
 
+:param x: the typed list to be reversed.
+"""
 
-class Index(Op):
 
+class Index(Op):
+    # See doc in instance of this Op after the class definition.
     def __eq__(self, other):
         return type(self) == type(other)
 
@@ -413,7 +446,7 @@ index_ = Index()
 
 
 class Count(Op):
-
+    # See doc in instance of this Op after the class definition.
     def __eq__(self, other):
         return type(self) == type(other)
 
@@ -441,6 +474,18 @@ class Count(Op):
         return self.__class__.__name__
 
 count = Count()
+"""
+Count the number of time an element is in the typed list.
+
+:param x: The typed list to look into.
+:param elem: The element we want to count in list.
+    The element are compared with equals.
+
+:note: Python implementation of count doesn't work when we want to
+    count an ndarray from a list. This implementation works in that
+    case.
+
+"""
 
 
 class Length(Op):