Merge pull request #3563 from abergeron/fix_doc

doc/library/d3viz/index.txt

 .. _libdoc_d3viz:
 
-============================================================================
+=========================================================================
 :mod:`d3viz` -- d3viz: Interactive visualization of Theano compute graphs
-============================================================================
+=========================================================================
 
-.. module:: d3viz
+.. module:: theano.d3viz
    :platform: Unix, Windows
    :synopsis: Allows to interactively visualize Theano compute graphs
 .. moduleauthor:: Christof Angermueller
@@ -109,7 +109,7 @@ the the :py:mod:`theano.d3viz.d3viz` module, which can be called as before:
     import theano.d3viz as d3v
     d3v.d3viz(predict, 'examples/mlp.html')
 
-`Open visualization! <../../_static/mlp.html>`_
+`Open visualization! <../../_static/mlp.html>`__
 
 When you open the output file ``mlp.html`` in your web-browser, you will
 see an interactive visualization of the compute graph. You can move the
@@ -150,7 +150,7 @@ random data:
 
     d3v.d3viz(predict_profiled, 'examples/mlp2.html')
 
-`Open visualization! <../../_static/mlp2.html>`_
+`Open visualization! <../../_static/mlp2.html>`__
 
 When you open the HTML file in your browser, you will find an additional
 ``Toggle profile colors`` button in the menu bar. By clicking on it,
@@ -213,7 +213,7 @@ defines a nested graph, which will be visualized accordingly by
 
     d3v.d3viz(f, 'examples/ofg.html')
 
-`Open visualization! <../../_static/ofg.html>`_
+`Open visualization! <../../_static/ofg.html>`__
 
 In this example, an operation with three inputs is defined, which is
 used to build a function that calls this operations twice, each time
@@ -243,7 +243,7 @@ the following example.
 
     d3v.d3viz(f, 'examples/ofg2.html')
 
-`Open visualization! <../../_static/ofg2.html>`_
+`Open visualization! <../../_static/ofg2.html>`__
 
 Feedback
 --------

doc/library/tensor/basic.txt

@@ -750,8 +750,10 @@ Creating Tensor
 
 .. function:: stack(*tensors)
 
-    .. warning:: The interface stack(*tensors) is deprecated! 
-             Use stack(tensors, axis=0) instead.
+    .. warning::
+
+        The interface `stack(*tensors)` is deprecated!  Use
+        `stack(tensors, axis=0)` instead.
 
     Stack tensors in sequence vertically (row wise).
 
@@ -1773,6 +1775,7 @@ Gradient / Differentiation
 
 .. automodule:: theano.gradient
     :members: grad
+    :noindex:
 
 See the :ref:`gradient <libdoc_gradient>` page for complete documentation
 of the gradient module.

doc/tutorial/debug_faq.txt

@@ -181,7 +181,7 @@ of error can thus be identified with much more precision and much earlier in
 the compilation pipeline. For example, running the above code yields the
 following error message, which properly identifies *line 24* as the culprit.
 
-.. code-block:: node
+.. code-block:: none
 
     Traceback (most recent call last):
       File "test2.py", line 24, in <module>

doc/tutorial/extending_theano_c.txt

@@ -878,7 +878,7 @@ pre-defined macros.  These section tags have no macros: ``init_code``,
 discussed below.
 
 *      ``APPLY_SPECIFIC(str)`` which will automatically append a name
-       unique to the :ref:`Apply node that applies the Op at the end
+       unique to the :ref:`Apply` node that applies the Op at the end
        of the provided ``str``. The use of this macro is discussed
        futher below.
 

theano/compile/builders.py

@@ -14,7 +14,7 @@ class OpFromGraph(gof.Op):
     This creates an `Op` from inputs and outputs lists of variables.
 
     The signature is similar to theano.function() and the resulting
-    `Op`'s perform will do the same operation as:
+    `Op`'s perform will do the same operation as::
 
         orig_function(inputs, outputs, **kwargs)
 

theano/compile/function_module.py

@@ -242,7 +242,7 @@ class Function(object):
 
     A Function instance may be serialized using the `pickle` or
     `cPickle` modules.  This will save all default inputs, the graph,
-    and *** to the pickle file (WRITEME).
+    and WRITEME to the pickle file.
 
     A Function instance have a ``trust_input`` field that default to
     False. When True, we don't do extra check of the input to give

theano/d3viz/d3viz.py

@@ -18,9 +18,9 @@ def replace_patterns(x, replace):
 
     Parameters
     ----------
-    s: str
+    s : str
         String on which function is applied
-    replace: dict
+    replace : dict
         `key`, `value` pairs where key is a regular expression and `value` a
         string by which `key` is replaced
     """
@@ -34,7 +34,7 @@ def escape_quotes(s):
 
     Parameters
     ----------
-    s: str
+    s : str
         String on which function is applied
     """
     s = re.sub(r'''(['"])''', r'\\\1', s)
@@ -66,10 +66,12 @@ def d3viz(fct, outfile, copy_deps=True, *args, **kwargs):
         Path to output HTML file.
     copy_deps : bool, optional
         Copy javascript and CSS dependencies to output directory.
-    *args : tuple, optional
-        Arguments passed to PyDotFormatter.
-    *kwargs : dict, optional
-        Arguments passed to PyDotFormatter.
+
+    Notes
+    -----
+    This function accepts extra parameters which will be forwarded to
+    :class:`theano.d3viz.formatting.PyDotFormatter`.
+
     """
 
     # Create DOT graph
@@ -121,10 +123,12 @@ def d3write(fct, path, *args, **kwargs):
         A compiled Theano function, variable, apply or a list of variables.
     path: str
         Path to output file
-    *args : tuple, optional
-        Arguments passed to PyDotFormatter.
-    *kwargs : dict, optional
-        Arguments passed to PyDotFormatter.
+
+    Notes
+    -----
+    This function accepts extra parameters which will be forwarded to
+    :class:`theano.d3viz.formatting.PyDotFormatter`.
+
     """
 
     formatter = PyDotFormatter(*args, **kwargs)

theano/gof/utils.py

@@ -192,13 +192,13 @@ def deprecated(filename, msg=''):
     """
     Decorator which will print a warning message on the first call.
 
-    Use it like this:
+    Use it like this::
 
       @deprecated('myfile', 'do something different...')
       def fn_name(...)
           ...
 
-    And it will print:
+    And it will print::
 
       WARNING myfile.fn_name deprecated. do something different...
 

theano/gradient.py

@@ -371,58 +371,51 @@ def grad(cost, wrt, consider_constant=None,
     see :mod:`gradient`. For information on how to implement the gradient of
     a certain Op, see :func:`grad`.
 
-    :type cost: Scalar (0-dimensional) tensor variable.
-        May optionally be None if known_grads is provided.
-    :param cost: a scalar with respect to which we are differentiating
+    Parameters
+    ----------
+    cost : scalar (0-dimensional) tensor variable or None
+        Value with respect to which we are differentiating.  May be
+        `None` if known_grads is provided.
+    wrt : variable or list of variables
+        term[s] for which we want gradients
+    consider_constant : list of variables
+        expressions not to backpropagate through
+    disconnected_inputs : {'ignore', 'warn', 'raise'}
+        Defines the behaviour if some of the variables in `wrt` are
+        not part of the computational graph computing `cost` (or if
+        all links are non-differentiable). The possible values are:
 
-    :type wrt: Tensor variable or list of variables.
-    :param wrt: term[s] for which we want gradients
-
-    :type consider_constant: list of variables
-    :param consider_constant: a list of expressions not to backpropagate
-        through
-
-    :type disconnected_inputs: string
-    :param disconnected_inputs: Defines the behaviour if some of the variables
-        in ``wrt`` are not part of the computational graph computing ``cost``
-        (or if all links are non-differentiable). The possible values are:
         - 'ignore': considers that the gradient on these parameters is zero.
         - 'warn': consider the gradient zero, and print a warning.
         - 'raise': raise DisconnectedInputError.
-
-    :type add_names: bool
-    :param add_names: If True, variables generated by grad will be named
-        (d<cost.name>/d<wrt.name>) provided that both cost and wrt have
-        names
-
-    :type known_grads: dict
-    :param known_grads: If not None, a dictionary mapping variables to their
-            gradients. This is useful in the case where you know the
-            gradient on some variables but do not know the original
-            cost.
-
-    :type return_disconnected: string
-    :param return_disconnected:
+    add_names : bool
+        If True, variables generated by grad will be named
+        (d<cost.name>/d<wrt.name>) provided that both cost and wrt
+        have names
+    known_grads : dict, optional
+        A dictionary mapping variables to their gradients. This is
+        useful in the case where you know the gradient on some
+        variables but do not know the original cost.
+    return_disconnected : {'zero', 'None', 'Disconnected'}
         - 'zero' : If wrt[i] is disconnected, return value i will be
                    wrt[i].zeros_like()
         - 'None' : If wrt[i] is disconnected, return value i will be
                    None
         - 'Disconnected' : returns variables of type DisconnectedType
+    null_gradients : {'raise', 'return'}
+        Defines the behaviour if some of the variables in `wrt` have a
+        null gradient. The possibles values are:
 
-    :type null_gradients: string
-    :param null_gradients: Defines the behaviour if some of the variables in
-            ``wrt`` have a null gradient. The possibles values are :
         - 'raise' : raise a NullTypeGradError exception
         - 'return' : return the null gradients
 
-    :rtype: variable or list/tuple of Variables (matching `wrt`)
-
-    :return: symbolic expression of gradient of `cost` with respect to each
-             of the `wrt` terms.
-             If an element of `wrt` is not differentiable with respect
-             to the output, then a zero variable is returned.
-             It returns an object of same type as `wrt`: a list/tuple
-             or Variable in all cases.
+    Returns
+    -------
+    variable or list/tuple of variables (matches `wrt`)
+        symbolic expression of gradient of `cost` with respect to each
+        of the `wrt` terms.  If an element of `wrt` is not
+        differentiable with respect to the output, then a zero
+        variable is returned.
 
     """
     t0 = time.time()

theano/sandbox/blocksparse.py

@@ -10,7 +10,8 @@ from theano.gradient import grad_undefined
 class SparseBlockGemv(Op):
     """
     This op computes the dot product of specified pieces of vectors
-    and matrices, returning pieces of vectors:
+    and matrices, returning pieces of vectors::
+
         for b in range(batch_size):
             for j in range(o.shape[1]):
                 for i in range(h.shape[1]):
@@ -20,6 +21,7 @@ class SparseBlockGemv(Op):
 
     .. image:: ../../images/blocksparse.png
         :scale: 50 %
+
     """
 
     registered_opts = []
@@ -34,29 +36,40 @@ class SparseBlockGemv(Op):
         Compute the dot product of the specified pieces of vectors
         and matrices.
 
+        The parameter types are actually their expected shapes
+        relative to each other.
+
         Parameters
         ----------
-        var: shape, comment
-        o: (batch, oWin, oSize) output vector
-        W: (iBlocks, oBlocks, iSize, oSize), weight matrix
-        h: (batch, iWin, iSize), input from lower layer (sparse)
-        inputIdx: (batch, iWin), indexes of the input blocks
-        outputIdx: (batch, oWin), indexes of the output blocks
-        returns (batch, oWin, oSize), dot(W[i, j], h[i]) + o[j]
-
-        Notation
-        --------
+        o : batch, oWin, oSize
+            output vector
+        W : iBlocks, oBlocks, iSize, oSize
+            weight matrix
+        h : batch, iWin, iSize
+            input from lower layer (sparse)
+        inputIdx : batch, iWin
+            indexes of the input blocks
+        outputIdx : batch, oWin
+            indexes of the output blocks
+
+        Returns
+        -------
+        (batch, oWin, oSize)
+            dot(W[i, j], h[i]) + o[j]
+
+        Notes
+        -----
         - `batch` is the number of examples in a minibatch (batch size).
         - `iBlocks` is the total number of blocks in the input (from lower
             layer).
         - `iSize` is the size of each of these input blocks.
         - `iWin` is the number of blocks that will be used as inputs. Which
-            blocks
-          will be used is specified in `inputIdx`.
+           blocks will be used is specified in `inputIdx`.
         - `oBlocks` is the number or possible output blocks.
         - `oSize` is the size of each of these output blocks.
         - `oWin` is the number of output blocks that will actually be computed.
             Which blocks will be computed is specified in `outputIdx`.
+
         """
         o = theano.tensor.as_tensor_variable(o)
         W = theano.tensor.as_tensor_variable(W)
@@ -118,10 +131,13 @@ class SparseBlockGemv(Op):
 class SparseBlockOuter(Op):
     """
     This computes the outer product of two sets of pieces of vectors
-    updating a full matrix with the results:
+    updating a full matrix with the results::
+
         for b in range(batch_size):
             o[xIdx[b, i], yIdx[b, j]] += (alpha * outer(x[b, i], y[b, j]))
+
     This op is involved in the gradient of SparseBlockGemv.
+
     """
 
     registered_opts = []
@@ -136,18 +152,26 @@ class SparseBlockOuter(Op):
         Compute the dot product of the specified pieces of vectors
         and matrices.
 
+        The parameter types are actually their expected shapes
+        relative to each other.
+
         Parameters
         ----------
-        var: shape, comment
-        o: (xBlocks, yBlocks, xSize, ySize)
-        x: (batch, xWin, xSize)
-        y: (batch, yWin, ySize)
-        xIdx: (batch, iWin), indexes of the x blocks
-        yIdx: (batch, oWin), indexes of the y blocks
-        returns (xBlocks, yBlocks, xSize, ySize), outer(x[i], y[j]) + o[i, j]
-
-        Notation
-        --------
+        o : xBlocks, yBlocks, xSize, ySize
+        x : batch, xWin, xSize
+        y : batch, yWin, ySize
+        xIdx : batch, iWin
+            indexes of the x blocks
+        yIdx : batch, oWin
+            indexes of the y blocks
+
+        Returns
+        -------
+        (xBlocks, yBlocks, xSize, ySize)
+            outer(x[i], y[j]) + o[i, j]
+
+        Notes
+        -----
         - `batch` is the number of examples in a minibatch (batch size).
         - `xBlocks` is the total number of blocks in x.
         - `xSize` is the size of each of these x blocks.
@@ -157,6 +181,7 @@ class SparseBlockOuter(Op):
         - `ySize` is the size of each of these y blocks.
         - `yWin` is the number of y blocks that will actually be computed.
           Which blocks will be computed is specified in `yIdx`.
+
         """
         one = tensor.constant(numpy.asarray(1.0, dtype='float32'))
         o = theano.tensor.as_tensor_variable(o)
@@ -197,18 +222,29 @@ def sparse_block_dot(W, h, inputIdx, b, outputIdx):
     Compute the dot product (plus bias) of the specified pieces of vectors
     and matrices. See SparseBlockGemv to get more information.
 
+    The parameter types are actually their expected shapes relative to
+    each other.
+
     Parameters
     ----------
-    var: shape, comment
-    W: (iBlocks, oBlocks, iSize, oSize), weight matrix
-    h: (batch, iWin, iSize), input from lower layer (sparse)
-    inputIdx: (batch, iWin), indexes of the input blocks
-    b: (oBlocks, oSize), bias vector
-    outputIdx: (batch, oWin), indexes of the output blocks
-    returns (batch, oWin, oSize), dot(W[i, j], h[i]) + b[j]
-         but b[j] is only added once
-    Notation
-    --------
+    W : iBlocks, oBlocks, iSize, oSize
+        weight matrix
+    h : batch, iWin, iSize
+        input from lower layer (sparse)
+    inputIdx : batch, iWin
+        indexes of the input blocks
+    b : oBlocks, oSize
+        bias vector
+    outputIdx : batch, oWin
+        indexes of the output blocks
+
+    Returns
+    -------
+    (batch, oWin, oSize)
+        dot(W[i, j], h[i]) + b[j] but b[j] is only added once
+
+    Notes
+    -----
     - `batch` is the number of examples in a minibatch (batch size).
     - `iBlocks` is the total number of blocks in the input (from lower layer).
     - `iSize` is the size of each of these input blocks.

theano/sandbox/cuda/dnn.py

@@ -588,9 +588,9 @@ class GpuDnnConv3d(GpuDnnConv):
     :param descr: the convolution descriptor
     :param workmem:
         *deprecated*, use parameter algo instead.
-    :param algo: ['none', 'guess_once', 'guess_on_shape_change',
-                  'time_once', 'time_on_shape_change']
-            Default is the value of :attr:`config.dnn.conv.algo_fwd.
+    :param algo: ['none', 'guess_once', 'guess_on_shape_change', 'time_once', 'time_on_shape_change']
+        Default is the value of :attr:`config.dnn.conv.algo_fwd`.
+
     """
     __props__ = ('algo', 'inplace')
     __input_name__ = ('image', 'kernel', 'output',
@@ -692,11 +692,7 @@ class GpuDnnConvGradW(DnnBase, COp):
         The convolution descriptor.
     workmem
         *deprecated*, use parameter algo instead.
-    algo
-        ['none', 'deterministic', 'fft', 'guess_once',
-         'guess_on_shape_change', 'time_once',
-         'time_on_shape_change']
-
+    algo : {'none', 'deterministic', 'fft', 'guess_once', 'guess_on_shape_change', 'time_once', 'time_on_shape_change'}
         Default is the value of :attr:`config.dnn.conv.algo_bwd`.
 
     """
@@ -831,8 +827,7 @@ class GpuDnnConv3dGradW(GpuDnnConvGradW):
     :param descr: the convolution descriptor
     :param workmem:
         *deprecated*, use parameter algo instead.
-    :param algo: ['none', 'guess_once', 'guess_on_shape_change',
-                  'time_once', 'time_on_shape_change']
+    :param algo: ['none', 'guess_once', 'guess_on_shape_change', 'time_once', 'time_on_shape_change']
         Default is the value of :attr:`config.dnn.conv.algo_bwd`.
 
     """
@@ -1104,8 +1099,8 @@ def dnn_conv(img, kerns, border_mode='valid', subsample=(1, 1),
     """
     GPU convolution using cuDNN from NVIDIA.
 
-    The memory layout to use is 'bc01', that is 'batch', 'channel', 'first dim',
-    'second dim' in that order.
+    The memory layout to use is 'bc01', that is 'batch', 'channel',
+    'first dim', 'second dim' in that order.
 
     Parameters
     ----------
@@ -1138,7 +1133,7 @@ def dnn_conv(img, kerns, border_mode='valid', subsample=(1, 1),
     algo : {'none', 'small', 'large', 'fft', 'guess_once', 'guess_on_shape_change', 'time_once', 'time_on_shape_change'}
 	Convolution implementation to use. Some of its  values may require certain
         versions of CuDNN to be installed. Default is the value of
-        :attr:`config.dnn.conv.algo_fwd.
+        :attr:`config.dnn.conv.algo_fwd`.
 
     """
 
@@ -1230,7 +1225,7 @@ def dnn_conv3d(img, kerns, border_mode='valid', subsample=(1, 1, 1),
     :param workmem: *deprecated*, use param algo instead
     :param algo: convolution implementation to use. Only 'none' is implemented
         for the conv3d. Default is the value of
-        :attr:`config.dnn.conv.algo_fwd.
+        :attr:`config.dnn.conv.algo_fwd`.
 
     :warning: The cuDNN library only works with GPU that have a compute
       capability of 3.0 or higer.  This means that older GPU will not

theano/sandbox/cuda/var.py

@@ -126,14 +126,17 @@ class CudaNdarraySharedVariable(_operators, SharedVariable):
 
             * The destination on the GPU must be c_contiguous.
             * The source is on the CPU.
-            * The old value must have the same dtype as the new value (which is
-            a given for now, since only float32 is supported).
+            * The old value must have the same dtype as the new value
+              (which is a given for now, since only float32 is
+              supported).
             * The old and new value must have the same shape.
-            * The old value is being completely replaced by the new value (not
-            partially modified, e.g. by replacing some subtensor of it).
-            * You change the value of the shared variable via set_value, not via
-            the .value accessors. You should not use the .value accessors
-            anyway, since they will soon be deprecated and removed.
+            * The old value is being completely replaced by the new
+              value (not partially modified, e.g. by replacing some
+              subtensor of it).
+            * You change the value of the shared variable via
+              set_value, not via the .value accessors. You should not
+              use the .value accessors anyway, since they will soon be
+              deprecated and removed.
 
         It is also worth mentioning that, for efficient transfer to the GPU,
         Theano will make the new data ``c_contiguous``. This can require an

theano/tensor/nnet/neighbours.py

@@ -14,22 +14,20 @@ from theano.gradient import grad_undefined
 
 class Images2Neibs(Op):
     """
+    Reshapes the input as a 2D tensor where each row is an pooling
+    example.
 
     Parameters
     ----------
     mode : {'valid', 'ignore_borders', 'wrap_centered'}
-        'valid': Requires an input that is a multiple of the
-            pooling factor (in each direction).
-        'ignore_borders': Same as valid, but will ignore the borders
-            if the shape(s) of the input is not a multiple of the pooling
-            factor(s).
-        'wrap_centered' : ?? TODO comment
-
-    Returns
-    -------
-    object
-        Reshapes the input as a 2D tensor where each row is an
-        pooling example.
+        - 'valid' :
+            Requires an input that is a multiple of the pooling factor
+            (in each direction).
+        - 'ignore_borders' :
+            Same as valid, but will ignore the borders if the shape(s)
+            of the input is not a multiple of the pooling factor(s).
+        - 'wrap_centered' :
+            ?? TODO comment
 
     """
 
@@ -429,7 +427,7 @@ class Images2Neibs(Op):
 
 def images2neibs(ten4, neib_shape, neib_step=None, mode='valid'):
     """
-    Function :func:`images2neibs <theano.sandbox.neighbours.images2neibs>`
+    Function :func:`images2neibs <theano.tensor.nnet.neighbours.images2neibs>`
     allows to apply a sliding window operation to a tensor containing
     images or other two-dimensional objects.
     The sliding window operation loops over points in input data and stores
@@ -455,9 +453,6 @@ def images2neibs(ten4, neib_shape, neib_step=None, mode='valid'):
         By default it is equal to `neib_shape` in other words, the patches are
         disjoint. When the step is greater than `neib_shape`, some elements are
         omitted. When None, this is the same as neib_shape (patch are disjoint).
-        .. note:: Currently the step size should be chosen in the way that the
-            corresponding dimension :math:`i` (width or height) is equal to
-            :math:`n * step\_size_i + neib\_shape_i` for some :math:`n`
     mode : {'valid', 'ignore_borders', 'wrap_centered'}
         ``valid``
             Requires an input that is a multiple of the
@@ -489,6 +484,13 @@ def images2neibs(ten4, neib_shape, neib_step=None, mode='valid'):
              these for loops, they're just the easiest way to describe the
              output pattern.
 
+    Notes
+    -----
+    .. note::
+        Currently the step size should be chosen in the way that the
+        corresponding dimension :math:`i` (width or height) is equal
+        to :math:`n * step\_size_i + neib\_shape_i` for some :math:`n`.
+
     Examples
     --------
 
@@ -524,7 +526,7 @@ def neibs2images(neibs, neib_shape, original_shape, mode='valid'):
 
     Parameters
     ----------
-    neibs: matrix
+    neibs : 2d tensor
         Like the one obtained by
         :func:`images2neibs <theano.sandbox.neigbours.neibs2images>`.
     neib_shape