Merge pull request #875 from nouiz/doc2

doc/library/sparse/index.txt

@@ -160,7 +160,8 @@ List of Implemented Operations
       The grad implemented is structured.
 
 - Monoid (Element-wise operation with only one sparse input).
-  `They all have a structured grad.`
+    `They all have a structured grad.`
+
     - ``structured_sigmoid``
     - ``structured_exp``
     - ``structured_log``
@@ -217,14 +218,16 @@ List of Implemented Operations
       The grad implemented is regular.
 
 - Probability
-  `There is no grad implemented for these operations.`
+    `There is no grad implemented for these operations.`
+
     - :class:`Poisson <theano.sparse.basic.Poisson>` and ``poisson``
     - :class:`Binomial <theano.sparse.basic.Binomial>` and ``csc_fbinomial``, ``csc_dbinomial``
       ``csr_fbinomial``, ``csr_dbinomial``
     - :class:`Multinomial <theano.sparse.basic.Multinomial>` and ``multinomial``
 
 - Internal Representation
-  `They all have a regular grad implemented.`
+    `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:`clean <theano.sparse.basic.clean>` to resort indices and remove zeros

doc/sandbox/index2.txt

@@ -8,7 +8,7 @@ Advanced Topics (under construction)
 .. toctree::
     :maxdepth: 2
 
-    fgraph
+    fg
     compilation
     ccodegen
     function

doc/tutorial/extending_theano.txt

@@ -333,4 +333,34 @@ Documentation
 -------------
 
 See :ref:`metadocumentation`, for some information on how to generate
-and do documentation.
+the documentation.
+
+Here is an example how to add docstring to an class.
+
+.. code-block:: python
+
+    import theano
+
+    class DoubleOp(theano.Op):
+    """ Double each element of a tensor.
+
+    :param x: input tensor.
+
+    :return: a tensor of the shape shape and dtype as the input with all
+        values doubled.
+
+    :note:
+        this is a test note
+
+    :seealso:
+        You can use the elemwise op to replace this example.
+        Just execute `x * 2` with x being a Theano variable.
+
+    .. versionadded:: 0.6
+    """
+
+This is how it will show up for file that we auto list in the library documentation:
+
+
+.. automodule:: theano.misc.doubleop
+    :members:

theano/misc/doubleop.py

+#This is the example in the Theano/doc/tutorial/extending_theano.txt
+
+import theano
+
+
+class DoubleOp(theano.Op):
+    """ Double each element of a tensor.
+
+    :param x: input tensor.
+
+    :return: a tensor of the shape shape and dtype as the input with all
+        values doubled.
+
+    :note:
+        this is a test note
+
+    :seealso:
+        You can use the elemwise op to replace this example.
+        Just execute `x * 2` with x being a Theano variable.
+
+    .. versionadded:: 0.6
+    """
+    def __eq__(self, other):
+        return type(self) == type(other)
+
+    def __hash__(self):
+        return hash(type(self))
+
+    def __str__(self):
+        return self.__class__.__name__
+
+    def make_node(self, x):
+        x = theano.tensor.as_tensor_variable(x)
+        return theano.Apply(self, [x], [x.type()])
+
+    def perform(self, node, inputs, output_storage):
+        x = inputs[0]
+        z = output_storage[0]
+        z[0] = x * 2
+
+    def infer_shape(self, node, i0_shapes):
+        return i0_shapes
+
+    def grad(self, inputs, output_grads):
+        return [output_grads[0] * 2]
+
+    def R_op(self, inputs, eval_points):
+        # R_op can receive None as eval_points.
+        # That mean there is no diferientiable path through that input
+        # If this imply that you cannot compute some outputs,
+        # return None for those.
+        if eval_points[0] is None:
+            return eval_points
+        return self.grad(inputs, eval_points)

theano/tensor/extra_ops.py

@@ -8,20 +8,7 @@ from theano.sandbox.linalg.ops import diag
 
 
 class DiffOp(theano.Op):
-    """Calculate the n-th order discrete difference along given axis.
-
-    The first order difference is given by out[n] = a[n+1] - a[n]
-    along the given axis, higher order differences are calculated by
-    using diff recursively. Wraping of numpy.diff.
-
-    Parameter:
-    x -- Input vector.
-
-    Keywords arguments:
-    n -- The number of times values are differenced, default is 1.
-
-    """
-
+    # See function diff for docstring
     def __init__(self, n=1, axis=-1):
         self.n = n
         self.axis = axis
@@ -78,40 +65,24 @@ class DiffOp(theano.Op):
 def diff(x, n=1, axis=-1):
     """Calculate the n-th order discrete difference along given axis.
 
-    The first order difference is given by out[n] = a[n+1] - a[n]
+    The first order difference is given by out[i] = a[i + 1] - a[i]
     along the given axis, higher order differences are calculated by
     using diff recursively. Wraping of numpy.diff.
 
-    Parameter:
-    x -- Input vector.
+    :param x: Input tensor variable.
 
-    Keywords arguments:
-    n -- The number of times values are differenced, default is 1.
+    :param n: The number of times values are differenced, default is 1.
 
+    :param axis: The axis along which the difference is taken,
+        default is the last axis.
+
+    .. versionadded:: 0.6
     """
     return DiffOp(n=n, axis=axis)(x)
 
 
 class BinCountOp(theano.Op):
-    """Count number of occurrences of each value in array of non-negative ints.
-
-    The number of bins (of size 1) is one larger than the largest
-    value in x. If minlength is specified, there will be at least
-    this number of bins in the output array (though it will be longer
-    if necessary, depending on the contents of x). Each bin gives the
-    number of occurrences of its index value in x. If weights is
-    specified the input array is weighted by it, i.e. if a value n
-    is found at position i, out[n] += weight[i] instead of out[n] += 1.
-    Wraping of numpy.bincount
-
-    Parameter:
-    x -- 1 dimension, nonnegative ints
-
-    Keywords arguments:
-    weights -- Weights, array of the same shape as x.
-    minlength -- A minimum number of bins for the output array.
-
-    """
+    # See function bincount for docstring
 
     compatible_type = ('int8', 'int16', 'int32', 'int64',
                        'uint8', 'uint16', 'uint32', 'uint64')
@@ -202,13 +173,14 @@ def bincount(x, weights=None, minlength=None):
     is found at position i, out[n] += weight[i] instead of out[n] += 1.
     Wraping of numpy.bincount
 
-    Parameter:
-    x -- 1 dimension, nonnegative ints
+    :param x: 1 dimension, nonnegative ints
 
-    Keywords arguments:
-    weights -- Weights, array of the same shape as x.
-    minlength -- A minimum number of bins for the output array.
+    :param weights: array of the same shape as x with corresponding weights.
+        Optional.
+    :param minlength: A minimum number of bins for the output array.
+        Optional.
 
+    .. versionadded:: 0.6
     """
     return BinCountOp(minlength=minlength)(x, weights)
 
@@ -224,6 +196,8 @@ def squeeze(x):
     :param x: Input data, tensor variable.
 
     :return: `x` without its broadcastable dimensions.
+
+    .. versionadded:: 0.6
     """
     view = x.dimshuffle([i for i in range(x.ndim)
                          if not x.broadcastable[i]])
@@ -231,21 +205,7 @@ def squeeze(x):
 
 
 class RepeatOp(theano.Op):
-    """Repeat elements of an array.
-
-    It returns an array which has the same shape as `x`, except
-    along the given axis. The axis is used to speficy along which
-    axis to repeat values. By default, use the flattened input
-    array, and return a flat output array.
-
-    The number of repetitions for each element is `repeat`.
-    `repeats` is broadcasted to fit the length of the given `axis`.
-
-    :param x: Input data, tensor variable.
-    :param repeats: int, scalar or tensor variable.
-
-    :param axis: int, optional.
-    """
+    # See the repeat function for docstring
 
     def __init__(self, axis=None):
         self.axis = axis
@@ -360,26 +320,14 @@ def repeat(x, repeats, axis=None):
     :param repeats: int, scalar or tensor variable.
 
     :param axis: int, optional.
+
+    .. versionadded:: 0.6
     """
     return RepeatOp(axis=axis)(x, repeats)
 
 
 class Bartlett(gof.Op):
-    """
-    An instance of this class returns the Bartlett spectral window in the
-    time-domain. The Bartlett window is very similar to a triangular window,
-    except that the end points are at zero. It is often used in signal
-    processing for tapering a signal, without generating too much ripple in
-    the frequency domain.
-
-    input : (integer scalar) Number of points in the output window. If zero or
-    less, an empty vector is returned.
-
-    output : (vector of doubles) The triangular window, with the maximum value
-    normalized to one (the value one appears only if the number of samples is
-    odd), with the first and last samples equal to zero.
-    """
-
+    # See function bartlett for docstring
     def __eq__(self, other):
         return type(self) == type(other)
 
@@ -414,33 +362,34 @@ class Bartlett(gof.Op):
 
     def grad(self, inputs, output_grads):
         return [None for i in inputs]
+bartlett_ = Bartlett()
 
 
-bartlett = Bartlett()
-
-
-class FillDiagonal(gof.Op):
-    """
-    An instance of this class returns a copy of an array with all elements of
-    the main diagonal set to a specified scalar value.
+#I create a function only to have the doc show well.
+def bartlett(M):
+    """An instance of this class returns the Bartlett spectral window in the
+    time-domain. The Bartlett window is very similar to a triangular window,
+    except that the end points are at zero. It is often used in signal
+    processing for tapering a signal, without generating too much ripple in
+    the frequency domain.
 
-    inputs:
+    :param M: (integer scalar) Number of points in the output
+        window. If zero or less, an empty vector is returned.
 
-    a : Rectangular array of at least two dimensions.
-    val : Scalar value to fill the diagonal whose type must be compatible with
-    that of array 'a' (i.e. 'val' cannot be viewed as an upcast of 'a').
+    :return: (vector of doubles) The triangular window, with the
+        maximum value normalized to one (the value one appears only if
+        the number of samples is odd), with the first and last samples
+        equal to zero.
 
-    output:
+    .. versionadded:: 0.6
 
-    An array identical to 'a' except that its main diagonal is filled with
-    scalar 'val'. (For an array 'a' with a.ndim >= 2, the main diagonal is the
-    list of locations a[i, i, ..., i] (i.e. with indices all identical).)
+    """
+    return bartlett_(M)
 
-    Support rectangular matrix and tensor with more then 2 dimensions
-    if the later have all dimensions are equals.
 
-    """
 
+class FillDiagonal(gof.Op):
+    # See function fill_diagonal for docstring
     def __eq__(self, other):
         return type(self) == type(other)
 
@@ -499,6 +448,27 @@ class FillDiagonal(gof.Op):
         wr_a = fill_diagonal(grad, 0)  # valid for any number of dimensions
         wr_val = diag(grad).sum()  # diag is only valid for matrices
         return [wr_a, wr_val]
+fill_diagonal_ = FillDiagonal()
+
+
+#I create a function only to have the doc show well.
+def fill_diagonal(a, val):
+    """ Returns a copy of an array with all
+    elements of the main diagonal set to a specified scalar value.
+
+    :param a: Rectangular array of at least two dimensions.
+    :param val: Scalar value to fill the diagonal whose type must be
+        compatible with that of array 'a' (i.e. 'val' cannot be viewed
+        as an upcast of 'a').
 
+    :return: An array identical to 'a' except that its main diagonal
+        is filled with scalar 'val'. (For an array 'a' with a.ndim >=
+        2, the main diagonal is the list of locations a[i, i, ..., i]
+        (i.e. with indices all identical).)
 
-fill_diagonal = FillDiagonal()
+    Support rectangular matrix and tensor with more then 2 dimensions
+    if the later have all dimensions are equals.
+
+    .. versionadded:: 0.6
+    """
+    return fill_diagonal_(a, val)