Fix most of the errors/warnings in the current docs.

NEWS.txt

-.. _NEWS:
-
 =============
 Release Notes
 =============

doc/crei2013/advanced_theano.txt

@@ -15,7 +15,7 @@ Profiling
 
 Theano output:
 
-.. literalinclude:: logreg_profile.txt
+.. literalinclude:: logreg_profile.prof
 
 Compilation pipeline
 --------------------

doc/extending/inplace.txt

@@ -216,5 +216,3 @@ optimization can pre-check whether it will get rejected by using the
 which Ops can be performed inplace. You may then skip the optimization if it is
 incompatible with this check. Note however that this check does not cover all
 cases where an optimization may be rejected (it will not detect cycles).
-
-.. _optdb:

doc/extending/other_ops.txt

@@ -176,19 +176,19 @@ has more implemented distributions.
 The slowest is our wrapper on NumPy's random generator.
 
 We explain and provide advice on 3 possibles implementations of new
-distributions here::
+distributions here:
 
-1) Extend our wrapper around NumPy random functions.
+1. Extend our wrapper around NumPy random functions.
    See this `PR <https://github.com/Theano/Theano/pull/1607>`_ as an example.
 
-2) Extend MRG implementation by reusing existing Theano Op. Look into
+2. Extend MRG implementation by reusing existing Theano Op. Look into
    the ``theano/sandbox/rng_mrg.py`` file and grep for all code about
    binomial(). This distribution uses the output of the uniform
    distribution and converts it to a binomial distribution with
    existing Theano operations. The tests go in
    ``theano/sandbox/test_rng_mrg.py``
 
-3) Extend MRG implementation with a new Op that takes a uniform sample as
+3. Extend MRG implementation with a new Op that takes a uniform sample as
    input. Look in the ``theano/sandbox/{rng_mrg,multinomial}.py`` file
    and its test in ``theano/sandbox/test_multinomal.py``. This is
    recommended when current Theano ops aren't well suited to modify

doc/index.txt

@@ -13,9 +13,10 @@ arrays efficiently. Theano features:
 * **dynamic C code generation** -- Evaluate expressions faster.
 * **extensive unit-testing and self-verification** -- Detect and diagnose many types of mistake.
 
-Theano has been powering large-scale computationally intensive scientific investigations
-since 2007.  But it is also approachable enough to be used in the classroom
-(IFT6266 at the University of Montreal).
+Theano has been powering large-scale computationally intensive
+scientific investigations since 2007.  But it is also approachable
+enough to be used in the classroom (IFT6266 at the University of
+Montreal).
 
 News
 ====
@@ -59,22 +60,24 @@ directory, so that when you pull updates via Git, they will be
 automatically reflected the "installed" version. For more information about
 installation and configuration, see :ref:`installing Theano <install>`.
 
-Status
-======
+.. only:: html
 
-.. image:: https://secure.travis-ci.org/Theano/Theano.png?branch=master
+  Status
+  ======
+
+  .. image:: https://secure.travis-ci.org/Theano/Theano.png?branch=master
       :target: http://travis-ci.org/Theano/Theano/builds
 
-.. image:: https://pypip.in/v/Theano/badge.png
+  .. image:: https://pypip.in/v/Theano/badge.png
       :target: https://crate.io/packages/Theano/
       :alt: Latest PyPI version
 
-.. image:: https://pypip.in/d/Theano/badge.png
+  .. image:: https://pypip.in/d/Theano/badge.png
       :target: https://crate.io/packages/Theano/
       :alt: Number of PyPI downloads
 
-.. _available on PyPI: http://pypi.python.org/pypi/Theano
-.. _Related Projects: https://github.com/Theano/Theano/wiki/Related-projects
+  .. _available on PyPI: http://pypi.python.org/pypi/Theano
+  .. _Related Projects: https://github.com/Theano/Theano/wiki/Related-projects
 
 Citing Theano
 ==============

doc/library/tensor/basic.txt

@@ -1545,7 +1545,8 @@ Linear Algebra
                  If an integer i, it is converted to an array containing
                  the last i dimensions of the first tensor and the first
                  i dimensions of the second tensor (excluding the first
-                 (batch) dimension):
+                 (batch) dimension)::
+
                      axes = [range(a.ndim - i, b.ndim), range(1,i+1)]
 
                  If an array, its two elements must contain compatible axes
@@ -1643,36 +1644,43 @@ Gradient / Differentiation
     >>>     next_grad = dict(zip(grad_ends[i], next_grad))
     >>>     param_grads.extend(param_grad)
 
-    :type wrt : List of Variables.
+    :type wrt: list of variables
+    :param wrt:
       Gradients are computed with respect to `wrt`.
 
-    :type end : List of Variables.
-        Theano variables at which to end gradient descent
-        (they are considered constant in theano.grad). 
-        For convenience, the gradients with respect to these variables 
-        are also returned.
+    :type end: list of variables
+    :param end:
+      Theano variables at which to end gradient descent (they are
+      considered constant in theano.grad).  For convenience, the
+      gradients with respect to these variables are also returned.
+
+    :type start: dictionary of variables
+    :param start:
+      If not None, a dictionary mapping variables to their
+      gradients. This is useful when the gradient on some variables
+      are known. These are used to compute the gradients backwards up
+      to the variables in `end` (they are used as known_grad in
+      theano.grad).
+
+    :type cost: scalar (0-dimensional) variable
+    :param cost:
 
-    :type start : Dictionary of Variables
-    :param start: If not None, a dictionary mapping variables to 
-            their gradients. This is useful when the gradient on some 
-            variables are known. These are used to compute the gradients
-            backwards up to the variables in `end` 
-            (they are used as known_grad in theano.grad).
+      Additional costs for which to compute the gradients.  For
+      example, these could be weight decay, an l1 constraint, MSE,
+      NLL, etc. May optionally be None if start is provided.
 
-    :type cost: Scalar (0-dimensional) Variable.
-    :param cost: 
-            Additional costs for which to compute the gradients.  
-            For example, these could be weight decay, an l1 constraint,
-            MSE, NLL, etc. May optionally be None if start is provided.
-            Warning : If the gradients of `cost` with respect to any 
-            of the `start` variables is already part of the `start` 
-            dictionary, then it may be counted twice with respect to `wrt` 
-            and `end`.
-    
-    :type details: bool.
-    :param details: When True, additionally returns the 
-        list of gradients from `start` and of `cost`, respectively, 
-        with respect to `wrt` (not `end`).
+      .. warning::
+
+        If the gradients of `cost` with respect to any of the `start`
+        variables is already part of the `start` dictionary, then it
+        may be counted twice with respect to `wrt` and `end`.
+
+    :type details: bool
+    :param details:
+
+      When True, additionally returns the list of gradients from
+      `start` and of `cost`, respectively, with respect to `wrt` (not
+      `end`).
 
     :rtype: Tuple of 2 or 4 Lists of Variables
 

doc/proposals/opencl.txt

-=======
-OpenCL
-=======
-
-Migrate the GPU code-generators to the PyCUDA style, and eventually to OpenCL.
-This means mainly to use a different kind of code-generation strategy.  The
-kernel itself is compiled, but the calling code remains in python or cython.  We
-would no longer generate entire C files this way, and no longer use the CLinker
-for GPU code.
-

doc/tutorial/modes.txt

@@ -137,7 +137,7 @@ Theano defines the following modes by name:
 - ``'DebugMode``: Verify the correctness of all optimizations, and compare C and Python 
     implementations. This mode can take much longer than the other modes, but can identify
     several kinds of problems.
-- ``'ProfileMode'``(deprecated): Same optimization as FAST_RUN, but print some profiling information.
+- ``'ProfileMode'`` (deprecated): Same optimization as FAST_RUN, but print some profiling information.
 
 The default mode is typically ``FAST_RUN``, but it can be controlled via
 the configuration variable :attr:`config.mode`,

doc/tutorial/profiling.txt

@@ -72,4 +72,4 @@ to run the example:
 
 The output:
 
-.. literalinclude:: profiling_example_out.txt
+.. literalinclude:: profiling_example_out.prof

doc/tutorial/using_gpu.txt

@@ -5,14 +5,16 @@
 Using the GPU
 =============
 
-For an introductory discussion of *Graphical Processing Units* (GPU) and their use for
-intensive parallel computation purposes, see `GPGPU <http://en.wikipedia.org/wiki/GPGPU>`_.
-
-One of Theano's design goals is to specify computations at an
-abstract level, so that the internal function compiler has a lot of flexibility
-about how to carry out those computations.  One of the ways we take advantage of
-this flexibility is in carrying out calculations on an Nvidia graphics card when
-the device present in the computer is CUDA-enabled.
+For an introductory discussion of *Graphical Processing Units* (GPU)
+and their use for intensive parallel computation purposes, see `GPGPU
+<http://en.wikipedia.org/wiki/GPGPU>`_.
+
+One of Theano's design goals is to specify computations at an abstract
+level, so that the internal function compiler has a lot of flexibility
+about how to carry out those computations.  One of the ways we take
+advantage of this flexibility is in carrying out calculations on an
+Nvidia graphics card when the device present in the computer is
+CUDA-enabled.
 
 Setting Up CUDA
 ----------------

theano/compile/builders.py

@@ -24,6 +24,7 @@ class OpFromGraph(gof.Op):
         - Add support for the GPU? Probably just need an opt to remove transfer
         - Add support to pickle this Op.
         - Add support/test with random generator
+
     :note:
         - We support shared variables in the inner graph. This is automatic and
           invisible to the user. They can be as input to the node or in the

theano/compile/ops.py

@@ -490,6 +490,7 @@ def register_rebroadcast_c_code(typ, code, version=()):
                  %(oname)s for the input and output C variable names
                  respectively.  %(axis)s for the axis that we need to
                  check. This code is put in a loop for all axis
+
     :param version: A number indicating the version of the code, for cache.
     """
     Rebroadcast.c_code_and_version[typ] = (code, version)
@@ -497,14 +498,18 @@ def register_rebroadcast_c_code(typ, code, version=()):
 
 class Rebroadcast(gof.Op):
     """
-    Change the input's broadcastable fields in
-    some predetermined way.
-    e.g.: Rebroadcast((0, True), (1, False))(x)
-          would make x broadcastable in axis 0
-          and not broadcastable in axis 1
-    See also the unbroadcast, addbroadcast and patternbroadcast functions.
-
-    ..note: work inplace and work for CudaNdarrayType
+    Change the input's broadcastable fields in some predetermined way.
+
+    :code:`Rebroadcast((0, True), (1, False))(x)` would make :code:`x`
+    broadcastable in axis 0 and not broadcastable in axis 1
+
+    .. seealso::
+
+      :func:`unbroadcast <theano.tensor.unbroadcast>`
+      :func:`addbroadcast <theano.tensor.addbroadcast>`
+      :func:`patternbroadcast <theano.tensor.patternbroadcast>`
+
+    ..note: works inplace and works for CudaNdarrayType
     """
     view_map = {0: [0]}
     # Mapping from Type to C code (and version) to use.

theano/gof/utils.py

@@ -95,13 +95,13 @@ def memoize(f):
 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

@@ -546,59 +546,65 @@ def grad(cost, wrt, consider_constant=None,
 
 def subgraph_grad(wrt, end, start=None, cost=None, details=False):
     '''
-    With respect to `wrt`, computes gradients of cost and/or from existing 
-    `start` gradients, up to the `end` variables of a symbolic digraph. 
-    In other words, computes gradients for a subgraph of the
-    symbolic theano function. Ignores all disconnected inputs.
+    With respect to `wrt`, computes gradients of cost and/or from
+    existing `start` gradients, up to the `end` variables of a
+    symbolic digraph.  In other words, computes gradients for a
+    subgraph of the symbolic theano function. Ignores all disconnected
+    inputs.
     
     This can be useful when one needs to perform the gradient descent
-    iteratively (e.g. one layer at a time in an MLP), or when a particular 
-    operation is not differentiable in theano (e.g. stochastic sampling 
-    from a multinomial). In the latter case, the gradient of the 
-    non-differentiable process could be approximated by user-defined 
-    formula, which could be calculated using the gradients of a cost 
-    with respect to samples (0s and 1s). These gradients are obtained 
-    by performing a subgraph_grad from the `cost` or previously known gradients 
-    (`start`) up to the outputs of the stochastic process (`end`). 
-    A dictionary mapping gradients obtained from the user-defined 
-    differentiation of the process, to variables, could then be fed into 
-    another subgraph_grad as `start` with any other `cost` (e.g. weight decay).
-    
-    :type wrt : List of Variables.
+    iteratively (e.g. one layer at a time in an MLP), or when a
+    particular operation is not differentiable in theano
+    (e.g. stochastic sampling from a multinomial). In the latter case,
+    the gradient of the non-differentiable process could be
+    approximated by user-defined formula, which could be calculated
+    using the gradients of a cost with respect to samples (0s and
+    1s). These gradients are obtained by performing a subgraph_grad
+    from the `cost` or previously known gradients (`start`) up to the
+    outputs of the stochastic process (`end`).  A dictionary mapping
+    gradients obtained from the user-defined differentiation of the
+    process, to variables, could then be fed into another
+    subgraph_grad as `start` with any other `cost` (e.g. weight
+    decay).
+    
+    :type wrt: list of variables
+    :param wrt:
       Gradients are computed with respect to `wrt`.
     
-    :type end : List of Variables.
-        Theano variables at which to end gradient descent
-        (they are considered constant in theano.grad). 
-        For convenience, the gradients with respect to these variables 
-        are also returned.
-    
-    :type start : Dictionary of Variables
-    :param start: If not None, a dictionary mapping variables to 
-            their gradients. This is useful when the gradient on some 
-            variables are known. These are used to compute the gradients
-            backwards up to the variables in `end` 
-            (they are used as known_grad in theano.grad).
-    
-    :type cost: Scalar (0-dimensional) Variable.
+    :type end: list of variables
+    :param end:
+      Theano variables at which to end gradient descent (they are
+      considered constant in theano.grad).  For convenience, the
+      gradients with respect to these variables are also returned.
+    
+    :type start: dictionary of variables
+    :param start:
+      If not None, a dictionary mapping variables to their
+      gradients. This is useful when the gradient on some variables
+      are known. These are used to compute the gradients backwards up
+      to the variables in `end` (they are used as known_grad in
+      theano.grad).
+    
+    :type cost: scalar (0-dimensional) variable
     :param cost: 
-            Additional costs for which to compute the gradients.  
-            For example, these could be weight decay, an l1 constraint,
-            MSE, NLL, etc. May optionally be None if start is provided.
-            Warning : If the gradients of `cost` with respect to any 
-            of the `start` variables is already part of the `start` 
-            dictionary, then it may be counted twice with respect to `wrt` 
-            and `end`.
-    
-    :type details: bool.
-    :param details: When True, additionally returns the 
-        list of gradients from `start` and of `cost`, respectively, 
-        with respect to `wrt` (not `end`).
+      Additional costs for which to compute the gradients.  For
+      example, these could be weight decay, an l1 constraint, MSE,
+      NLL, etc. May optionally be None if start is provided.  Warning
+      : If the gradients of `cost` with respect to any of the `start`
+      variables is already part of the `start` dictionary, then it may
+      be counted twice with respect to `wrt` and `end`.
+    
+    :type details: bool
+    :param details:
+      When True, additionally returns the list of gradients from
+      `start` and of `cost`, respectively, with respect to `wrt` (not
+      `end`).
     
     :rtype: Tuple of 2 or 4 Lists of Variables
     
     :return: Returns lists of gradients with respect to `wrt` and `end`, 
             respectively.
+
     '''
     assert ((cost is not None) or (start is not None))
     assert isinstance(end, list)

theano/sandbox/rng_mrg.py

@@ -999,8 +999,9 @@ def guess_n_streams(size, warn=True):
     """
     Return a guess at a good number of streams.
 
-    :param warn: If True, warn when a guess cannot be made (in which case
-    we return 60 * 256).
+    :param warn:
+      If True, warn when a guess cannot be made (in which case we
+      return 60 * 256).
     """
     # TODO: a smart way of choosing the number of streams, see #612.
     # Note that this code was moved out of `MRG_RandomStreams` so that it can
@@ -1134,20 +1135,25 @@ class MRG_RandomStreams(object):
         ndim may be a plain integer to supplement the missing
         information.
 
-        :param low: Lower bound of the interval on which values are sampled.
-        If the ``dtype`` arg is provided, ``low`` will be cast into dtype.
-        This bound is excluded.
+        :param low:
+          Lower bound of the interval on which values are sampled.  If
+          the ``dtype`` arg is provided, ``low`` will be cast into
+          dtype.  This bound is excluded.
 
-        :param high: Higher bound of the interval on which values are sampled.
-        If the ``dtype`` arg is provided, ``high`` will be cast into dtype.
-        This bound is excluded.
+        :param high:
+          Higher bound of the interval on which values are sampled.
+          If the ``dtype`` arg is provided, ``high`` will be cast into
+          dtype.  This bound is excluded.
 
-        :param size: Can be a list of integer or Theano variable
-                (ex: the shape of other Theano Variable)
+        :param size:
+          Can be a list of integer or Theano variable (ex: the shape
+          of other Theano Variable)
+
+        :param dtype:
+          The output data type. If dtype is not specified, it will be
+          inferred from the dtype of low and high, but will be at
+          least as precise as floatX.
 
-        :param dtype: The output data type. If dtype is not specified, it will
-        be inferred from the dtype of low and high, but will be at least as
-        precise as floatX.
         """
         low = as_tensor_variable(low)
         high = as_tensor_variable(high)
@@ -1274,14 +1280,18 @@ class MRG_RandomStreams(object):
     def normal(self, size, avg=0.0, std=1.0, ndim=None,
                dtype=None, nstreams=None):
         """
-        :param size: Can be a list of integers or Theano variables (ex: the
-        shape of another Theano Variable)
+        :param size:
+          Can be a list of integers or Theano variables (ex: the shape
+          of another Theano Variable)
+
+        :param dtype:
+          The output data type. If dtype is not specified, it will be
+          inferred from the dtype of low and high, but will be at
+          least as precise as floatX.
 
-        :param dtype: The output data type. If dtype is not specified, it will
-        be inferred from the dtype of low and high, but will be at least as
-        precise as floatX.
+        :param nstreams:
+          Number of streams.
 
-        :param nstreams: Number of streams.
         """
         # We need an even number of ]0,1[ samples. Then we split them
         # in two halves. First half becomes our U1's for Box-Muller,

theano/tensor/nnet/Conv3D.py

@@ -66,8 +66,10 @@ class Conv3D(theano.Op):
         b_ = T.as_tensor_variable(b)
         d_ = T.as_tensor_variable(d)
 
-        node = theano.Apply(self, inputs=[V_, W_,b_,d_], outputs = [ T.TensorType(V_.dtype, (V_.broadcastable[0],False,False,False, W_.broadcastable[0]))() ] )
+        bcast = (V_.broadcastable[0], False, False, False, W_.broadcastable[0])
 
+        node = theano.Apply(self, inputs=[V_, W_, b_, d_],
+                            outputs=[T.TensorType(V_.dtype, bcast)()])
 
         return node
 
@@ -118,8 +120,6 @@ class Conv3D(theano.Op):
         dCdW.name = 'Conv3D_dCdW(dCdH='+dCdH_name+',V='+V_name+',W='+W_name+')'
         dCdb.name = 'Conv3D_dCdb(dCdH='+dCdH_name+',V='+V_name+',W='+W_name+',b='+b_name+')'
 
-
-
         return [ dCdV, dCdW, dCdb, dCdd ]
 
     def perform(self, node, inputs, output_storage):
@@ -149,8 +149,7 @@ class Conv3D(theano.Op):
 
         rval = (batch_size,  output_height, output_width, output_dur, output_channels )
 
-
-        return [ rval ]
+        return [rval]
 
     def c_support_code(self):
         return blas_header_text()
@@ -174,7 +173,6 @@ class Conv3D(theano.Op):
 
         H = outputs[0]
 
-
         codeSource =  """
             ///////////// < code generated by Conv3D >
 
@@ -279,7 +277,6 @@ class Conv3D(theano.Op):
             const long long outputWidth = int( (vidWidth - filterWidth) / dc )+1;
             const long long outputDur = int( (vidDur - filterDur) / dt ) +1;
 
-
             npy_intp dims[5];
             dims[0] = batchSize;
             dims[4] = outputChannels;
@@ -287,8 +284,6 @@ class Conv3D(theano.Op):
             dims[2] = outputWidth;
             dims[3] = outputDur;
 
-
-
             if(!(%(H)s) || PyArray_DIMS(%(H)s)[0]!=dims[0] ||
             PyArray_DIMS(%(H)s)[1]!=dims[1] ||
             PyArray_DIMS(%(H)s)[2]!=dims[2] ||
@@ -303,10 +298,8 @@ class Conv3D(theano.Op):
             }
 { // extra scope so fail works
 
-
             #define ELEM_AT(x, i) * ( dtype_ ## x *) ( PyArray_BYTES(x) + (i) )
 
-
             const int ws0 = PyArray_STRIDES(%(W)s)[0];
             const int ws1 = PyArray_STRIDES(%(W)s)[1];
             const int ws2 = PyArray_STRIDES(%(W)s)[2];
@@ -319,22 +312,14 @@ class Conv3D(theano.Op):
             const int bs  = PyArray_STRIDES(%(b)s)[0];
             const int hs4 = PyArray_STRIDES(%(H)s)[4];
 
-
-
             // Compute H
             //H[i,j,x,y,t] = b_j + sum_k sum_l sum_m sum_z W[j,z,k,l,m] V[i,z, dr*r+k,dc*c+l,dt*t+m]
             //TODO: add special cases
             // ex: filterDur == 1 && batchSize == 1 && dt = 1  (for SFA)
             // ex: inputChannels == 1 """
 
-
-
-
-
-
-
-
-        #if the data types are not mixed, we can insert special case optimizations based on BLAS
+        # if the data types are not mixed, we can insert special case
+        # optimizations based on BLAS
         VV, WV, bv, dv = node.inputs
         HV = node.outputs[0]
         if (theano.config.blas.ldflags and
@@ -546,7 +531,7 @@ class Conv3D(theano.Op):
 
         return strutil.render_string(codeSource,locals())
 
-global conv3D
+
 conv3D = Conv3D()
 """
 3D "convolution" of multiple filters on a minibatch