Merge pull request #3302 from harlouci/numpydoc_scan_module

theano/scan_module/__init__.py

 """
-This module provides the Scan Op
+This module provides the Scan Op.
 
 Scanning is a general form of recurrence, which can be used for looping.
 The idea is that you *scan* a function along some input sequence, producing
@@ -26,9 +26,8 @@ the symbolic graph.
 The Scan Op should typically be used by calling any of the following
 functions: ``scan()``, ``map()``, ``reduce()``, ``foldl()``,
 ``foldr()``.
-"""
-
 
+"""
 __docformat__ = 'restructedtext en'
 __authors__ = ("Razvan Pascanu "
                "Frederic Bastien "

theano/scan_module/scan.py

 """
-This module provides the Scan Op
+This module provides the Scan Op.
 
 Scanning is a general form of recurrence, which can be used for looping.
 The idea is that you *scan* a function along some input sequence, producing
@@ -32,6 +32,7 @@ host at each step
 The Scan Op should typically be used by calling any of the following
 functions: ``scan()``, ``map()``, ``reduce()``, ``foldl()``,
 ``foldr()``.
+
 """
 __docformat__ = 'restructedtext en'
 __authors__ = ("Razvan Pascanu "
@@ -84,7 +85,9 @@ def scan(fn,
     This function constructs and applies a Scan op to the provided
     arguments.
 
-    :param fn:
+    Parameters
+    ----------
+    fn
         ``fn`` is a function that describes the operations involved in one
         step of ``scan``. ``fn`` should construct variables describing the
         output of one iteration step. It should expect as input theano
@@ -175,7 +178,7 @@ def scan(fn,
         number of steps ) is still required even though a condition is
         passed (and it is used to allocate memory if needed). = {}):
 
-    :param sequences:
+    sequences
         ``sequences`` is the list of Theano variables or dictionaries
         describing the sequences ``scan`` has to iterate over. If a
         sequence is given as wrapped in a dictionary, then a set of optional
@@ -193,8 +196,7 @@ def scan(fn,
         Any Theano variable in the list ``sequences`` is automatically
         wrapped into a dictionary where ``taps`` is set to ``[0]``
 
-
-    :param outputs_info:
+    outputs_info
         ``outputs_info`` is the list of Theano variables or dictionaries
         describing the initial state of the outputs computed
         recurrently. When this initial states are given as dictionary
@@ -252,15 +254,13 @@ def scan(fn,
         raised (because there is no convention on how scan should map
         the provided information to the outputs of ``fn``)
 
-
-    :param non_sequences:
+    non_sequences
         ``non_sequences`` is the list of arguments that are passed to
         ``fn`` at each steps. One can opt to exclude variable
         used in ``fn`` from this list as long as they are part of the
         computational graph, though for clarity we encourage not to do so.
 
-
-    :param n_steps:
+    n_steps
         ``n_steps`` is the number of steps to iterate given as an int
         or Theano scalar. If any of the input sequences do not have
         enough elements, scan will raise an error. If the *value is 0* the
@@ -270,8 +270,7 @@ def scan(fn,
         in time. If n_steps is not provided, ``scan`` will figure
         out the amount of steps it should run given its input sequences.
 
-
-    :param truncate_gradient:
+    truncate_gradient
         ``truncate_gradient`` is the number of steps to use in truncated
         BPTT.  If you compute gradients through a scan op, they are
         computed using backpropagation through time. By providing a
@@ -279,16 +278,14 @@ def scan(fn,
         of classical BPTT, where you go for only ``truncate_gradient``
         number of steps back in time.
 
-
-    :param go_backwards:
+    go_backwards
         ``go_backwards`` is a flag indicating if ``scan`` should go
         backwards through the sequences. If you think of each sequence
         as indexed by time, making this flag True would mean that
         ``scan`` goes back in time, namely that for any sequence it
         starts from the end and goes towards 0.
 
-
-    :param name:
+    name
         When profiling ``scan``, it is crucial to provide a name for any
         instance of ``scan``. The profiler will produce an overall
         profile of your code as well as profiles for the computation of
@@ -296,7 +293,7 @@ def scan(fn,
         appears in those profiles and can greatly help to disambiguate
         information.
 
-    :param mode:
+    mode
         It is recommended to leave this argument to None, especially
         when profiling ``scan`` (otherwise the results are not going to
         be accurate). If you prefer the computations of one step of
@@ -305,7 +302,7 @@ def scan(fn,
         loop are done (see ``theano.function`` for details about
         possible values and their meaning).
 
-    :param profile:
+    profile
         Flag or string. If true, or different from the empty string, a
         profile object will be created and attached to the inner graph of
         scan. In case ``profile`` is True, the profile object will have the
@@ -314,25 +311,27 @@ def scan(fn,
         inner graph with the new cvm linker ( with default modes,
         other linkers this argument is useless)
 
-    :param allow_gc:
+    allow_gc
         Set the value of allow gc for the internal graph of scan.  If
         set to None, this will use the value of config.scan.allow_gc.
 
-    :param strict:
+    strict
         If true, all the shared variables used in ``fn`` must be provided as a
         part of ``non_sequences`` or ``sequences``.
 
-    :rtype: tuple
-    :return: tuple of the form (outputs, updates); ``outputs`` is either a
-             Theano variable or a list of Theano variables representing the
-             outputs of ``scan`` (in the same order as in
-             ``outputs_info``). ``updates`` is a subclass of dictionary
-             specifying the
-             update rules for all shared variables used in scan
-             This dictionary should be passed to ``theano.function`` when
-             you compile your function. The change compared to a normal
-             dictionary is that we validate that keys are SharedVariable
-             and addition of those dictionary are validated to be consistent.
+    Returns
+    -------
+    tuple
+        Tuple of the form (outputs, updates); ``outputs`` is either a
+        Theano variable or a list of Theano variables representing the
+        outputs of ``scan`` (in the same order as in ``outputs_info``).
+        ``updates`` is a subclass of dictionary specifying the update rules for
+        all shared variables used in scan.
+        This dictionary should be passed to ``theano.function`` when you compile
+        your function. The change compared to a normal dictionary is that we
+        validate that keys are SharedVariable and addition of those dictionary
+        are validated to be consistent.
+
     """
     # General observation : this code is executed only once, at creation
     # of the computational graph, so we don't yet need to be smart about
@@ -344,9 +343,10 @@ def scan(fn,
 
     # check if inputs are just single variables instead of lists
     def wrap_into_list(x):
-        '''
-        Wrap the input into a list if it is not already a list
-        '''
+        """
+        Wrap the input into a list if it is not already a list.
+
+        """
         if x is None:
             return []
         elif not isinstance(x, (list, tuple)):
@@ -534,7 +534,7 @@ def scan(fn,
 
     if len(lengths_vec) == 0:
         # ^ No information about the number of steps
-        raise ValueError(' No information about the number of steps '
+        raise ValueError('No information about the number of steps '
                          'provided. Either provide a value for '
                          'n_steps argument of scan or provide an input '
                          'sequence')

theano/scan_module/scan_op.py

 """
-This module provides the Scan Op
+This module provides the Scan Op.
 
-See scan.py for details on scan
+See scan.py for details on scan.
 
 
 Memory reuse in scan
@@ -44,6 +44,7 @@ relies on the following elements to work properly :
   the outputs are stored as they are computed which means that, if the buffer
   is too small, computing an output can overwrite an input that is still
   needed to compute another output.
+
 """
 from __future__ import print_function
 
@@ -96,35 +97,43 @@ AddConfigVar('scan.allow_output_prealloc',
 
 
 class Scan(PureOp):
+    """
+
+    Parameters
+    ----------
+    inputs
+        Inputs of the inner function of scan.
+    outputs
+        Outputs of the inner function of scan.
+    info
+        Dictionary containing different properties of the scan op (like number
+        of different types of arguments, name, mode, if it should run on GPU or
+        not, etc.).
+    typeConstructor
+        Function that constructs an equivalent to Theano TensorType.
+
+    Notes
+    -----
+    ``typeConstructor`` had been added to refactor how
+    Theano deals with the GPU. If it runs on the GPU, scan needs
+    to construct certain outputs (those who reside in the GPU
+    memory) as the GPU-specific type.  However we can not import
+    gpu code in this file (as it is in sandbox, and not available
+    on each machine) so the workaround is that the GPU
+    optimization passes to the constructor of this class a
+    function that is able to construct a GPU type. This way the
+    class Scan does not need to be aware of the details for the
+    GPU, it just constructs any tensor using this function (which
+    by default constructs normal tensors).
+
+    """
+
     def __init__(self,
                  inputs,
                  outputs,
                  info,
                  typeConstructor=None,
                 ):
-        """
-        :param inputs: inputs of the inner function of scan
-        :param outputs: outputs of the inner function of scan
-        :param info: dictionary containing different properties of
-            the scan op (like number of different types of
-            arguments, name, mode, if it should run on GPU or
-            not, etc.)
-        :param typeConstructor: function that constructs an equivalent
-            to Theano TensorType
-
-
-        Note: ``typeConstructor`` had been added to refactor how
-        Theano deals with the GPU. If it runs on the GPU, scan needs
-        to construct certain outputs (those who reside in the GPU
-        memory) as the GPU-specific type.  However we can not import
-        gpu code in this file (as it is in sandbox, and not available
-        on each machine) so the workaround is that the GPU
-        optimization passes to the constructor of this class a
-        function that is able to construct a GPU type. This way the
-        class Scan does not need to be aware of the details for the
-        GPU, it just constructs any tensor using this function (which
-        by default constructs normal tensors).
-        """
         if 'gpua' not in info:
             info['gpua'] = False
         # adding properties into self
@@ -228,8 +237,10 @@ class Scan(PureOp):
         self.var_mappings = self.get_oinp_iinp_iout_oout_mappings()
 
     def validate_inner_graph(self):
-        """ Perform some elementary validations on the inner graph to ensure
+        """
+        Perform some elementary validations on the inner graph to ensure
         that it is coherent.
+
         """
 
         # For every recurrent output, iterate over the associated inner
@@ -323,6 +334,7 @@ class Scan(PureOp):
             inner_X_out - the variable representing the new value of X after
                           executing one step of scan (i.e. outputs given by
                           the inner function)
+
         """
         assert numpy.all(isinstance(i, gof.Variable) for i in inputs)
         # Check that the number of inputs to the Scan node corresponds to
@@ -391,10 +403,12 @@ class Scan(PureOp):
                    )
 
         def format(var, as_var):
-            """ This functions ensures that ``out`` has the same dtype as
+            """
+            This functions ensures that ``out`` has the same dtype as
             ``inp`` as well as calling filter_variable to make sure they are
             both TensorType or CudaNdarrayType. It internally deals with the
             corner case where inp.ndim + 1 = out.ndim
+
             """
             if not hasattr(var, 'dtype'):
                 return var
@@ -686,24 +700,31 @@ class Scan(PureOp):
 
     def make_thunk(self, node, storage_map, compute_map, no_recycling):
         """
-        :param node: something previously returned by self.make_node
 
-        :param storage_map: dict variable -> one-element-list where a computed
-                value for this variable may be found.
+        Parameters
+        ----------
+        node
+            Something previously returned by self.make_node.
+        storage_map
+            dict variable -> one-element-list where a computed
+            value for this variable may be found.
+        compute_map
+            dict variable -> one-element-list where a boolean
+            value will be found. The boolean indicates whether the
+            variable's storage_map container contains a valid value (True)
+            or if it has not been computed yet (False).
+        no_recycling
+            List of variables for which it is forbidden to reuse memory
+            allocated by a previous call.
+
+        Notes
+        -----
+        If the thunk consults the storage_map on every call, it is safe
+        for it to ignore the no_recycling argument, because elements of the
+        no_recycling list will have a value of None in the storage map. If
+        the thunk can potentially cache return values (like CLinker does),
+        then it must not do so for variables in the no_recycling list.
 
-        :param compute_map: dict variable -> one-element-list where a boolean
-                value will be found.  The boolean indicates whether the
-                variable's storage_map container contains a valid value (True)
-                or if it has not been computed yet (False).
-
-        :param no_recycling: list of variables for which it is forbidden to
-                reuse memory allocated by a previous call.
-
-        :note: If the thunk consults the storage_map on every call, it is safe
-            for it to ignore the no_recycling argument, because elements of the
-            no_recycling list will have a value of None in the storage map.  If
-            the thunk can potentially cache return values (like CLinker does),
-            then it must not do so for variables in the no_recycling list.
         """
 
         # Before building the thunk, validate that the inner graph is
@@ -1531,7 +1552,8 @@ class Scan(PureOp):
         return connection_pattern
 
     def get_oinp_iinp_iout_oout_mappings(self):
-        """ Compute and return dictionary mappings between the inputs and
+        """ 
+        Compute and return dictionary mappings between the inputs and
         outputs of the inner function and the inputs and outputs of the Scan
         node in the outer graph.
 
@@ -1541,7 +1563,8 @@ class Scan(PureOp):
         the values are individual integer indices. In dictionaries
         representing mappings to inner variables, the values are sequences of
         indices because multiple inner variables can be associated with the
-        same state
+        same state.
+
         """
         # Lists for outer variables contain individual indices, lists for
         # inner variables contain sequences of indices because many inner

theano/scan_module/scan_opt.py

 """
-This module provides optimizations for scan
+This module provides optimizations for scan.
 The Optimization provided in this file:
 
 local opt: remove_constants_and_unused_inputs_scan,
@@ -48,9 +48,8 @@ scan_eqopt2 -> They are all global optimizer. (in2out convert local to global).
                in2out(scan_merge_inouts),
                ScanSaveMem,
                in2out(remove_constants_and_unused_inputs_scan3)
-"""
-
 
+"""
 __docformat__ = 'restructedtext en'
 __authors__ = ("Razvan Pascanu "
                "Frederic Bastien "
@@ -104,7 +103,7 @@ def info(*msg):
 
 @gof.local_optimizer([scan_op.Scan])
 def remove_constants_and_unused_inputs_scan(node):
-    '''
+    """
     Move constants into the inner graph, and remove unused inputs.
 
     Constants that are in the outer graph are represented by a free symbolic
@@ -112,7 +111,8 @@ def remove_constants_and_unused_inputs_scan(node):
     constant-folding can happen in the inner graph.
     This is applied only on sequences and non-sequences,
     not on initial states.
-    '''
+
+    """
     if not isinstance(node.op, scan_op.Scan):
         return False
     op = node.op
@@ -214,7 +214,9 @@ class PushOutNonSeqScan(gof.Optimizer):
     """
     A global optimizer for pushing out the variables inside the scan that
     are not used by the scan.
+
     """
+
     def __init__(self):
         gof.Optimizer.__init__(self)
 
@@ -233,6 +235,7 @@ class PushOutNonSeqScan(gof.Optimizer):
         By default they are not ordered for efficiency reasons. Take care
         and make sure of changing them with their Ordered counterparts if you
         need to iterate over these variables.
+
         """
         # this flag tells if there was any change during the last iterations
         clean_inputs, clean_outputs = scan_utils.reconstruct_graph(
@@ -410,7 +413,9 @@ class PushOutSeqScan(gof.Optimizer):
     """
     A global optimizer for pushing out the input variables that are not being
     used inside the scan and provided in the sequences.
+
     """
+
     def __init__(self):
         gof.Optimizer.__init__(self)
 
@@ -429,6 +434,7 @@ class PushOutSeqScan(gof.Optimizer):
         By default they are not ordered for efficiency reasons. Take care
         and make sure of changing them to Ordered versions if you need to
         iterate over those variables.
+
         """
         # this flag tells if there was any change during the last iterations
         clean_inputs, clean_outputs = scan_utils.reconstruct_graph(
@@ -653,7 +659,9 @@ class PushOutScanOutput(gof.Optimizer):
     """
     This is an optimization that can push operations performed
     at the end of the inner graph of scan to outside of scan.
+
     """
+
     def __init__(self):
         gof.Optimizer.__init__(self)
 
@@ -701,8 +709,8 @@ class PushOutScanOutput(gof.Optimizer):
                 The Dot product is pushed out of the scan and its inputs are
                 now the original matrix and a new matrix obtained by
                 concatenating the vectors into a matrix.
+ 
                 """
-
                 # Ensure that the output of the Dot is used in the outer
                 # graph to avoid apply the optimization needlessly
                 dot_out_nitsot_idx = args.inner_out_nit_sot.index(nd.out)
@@ -715,6 +723,7 @@ class PushOutScanOutput(gof.Optimizer):
                 non-sequence input to scan and that the other input is a
                 vector and either an sequence input to scan or the result
                 of computation in the inner function of scan.
+ 
                 """
                 valid_inputs = False
                 idx_matrix_input = -1
@@ -863,6 +872,7 @@ class PushOutScanOutput(gof.Optimizer):
         nit_sot output has only one client and that client is a Subtensor
         instance that takes only the last step (last element along the first
         axis).
+
         """
         idx = scan_args.inner_out_sit_sot.index(var)
         outer_var = scan_args.outer_out_sit_sot[idx]
@@ -988,7 +998,11 @@ class PushOutScanOutput(gof.Optimizer):
 
 
 class ScanInplaceOptimizer(Optimizer):
-    """Graph optimizer for Scan(makes it run inplace)"""
+    """
+    Graph optimizer for Scan (makes it run inplace).
+
+    """
+
     def __init__(self, typeConstructor=None, gpu_flag=False, gpua_flag=False):
         Optimizer.__init__(self)
         self.typeConstructor = typeConstructor
@@ -1052,7 +1066,11 @@ class ScanInplaceOptimizer(Optimizer):
 
 
 class ScanSaveMem(gof.Optimizer):
-    """ Graph Optimizer that reduces scan memory consumption """
+    """
+    Graph Optimizer that reduces scan memory consumption.
+
+    """
+
     def __init__(self):
         gof.Optimizer.__init__(self)
 
@@ -1604,7 +1622,11 @@ class ScanSaveMem(gof.Optimizer):
 
 
 class ScanMerge(gof.Optimizer):
-    """ Graph Optimizer that merges different scan ops """
+    """
+    Graph Optimizer that merges different scan ops.
+
+    """
+
     def add_requirements(self, fgraph):
         fgraph.attach_feature(gof.toolbox.ReplaceValidate())
 
@@ -1783,6 +1805,7 @@ class ScanMerge(gof.Optimizer):
         over the same number of steps, have the same condition (if any),
         have the same value for truncate_gradient, and have the same mode.
         Questionable, we should also consider profile ?
+
         """
         rep = set_nodes[0]
         if rep.op.as_while != node.op.as_while:
@@ -1852,13 +1875,19 @@ class ScanMerge(gof.Optimizer):
 
 
 def has_duplicates(l):
-    """returns true if l has any duplicates (according to __eq__)."""
+    """
+    Returns true if l has any duplicates (according to __eq__).
+
+    """
     return len(set(l)) < len(l)
 
 
 def make_equiv(lo, li):
-    """builds a dictionary of equivalences between inner inputs based on
-    the equivalence of their corresponding outer inputs."""
+    """
+    Builds a dictionary of equivalences between inner inputs based on
+    the equivalence of their corresponding outer inputs.
+
+    """
     seeno = OrderedDict()
     left = []
     right = []
@@ -2034,7 +2063,11 @@ def scan_merge_inouts(node):
 
 
 class PushOutDot1(gof.Optimizer):
-    """Graph optimizer for Scan(makes it run inplace)"""
+    """
+    Graph optimizer for Scan(makes it run inplace).
+
+    """
+
     def __init__(self):
         Optimizer.__init__(self)
 

theano/scan_module/scan_utils.py

 """
-This module provides utility functions for the Scan Op
+This module provides utility functions for the Scan Op.
+
+See scan.py for details on scan.
 
-See scan.py for details on scan
 """
 __docformat__ = 'restructedtext en'
 __authors__ = ("Razvan Pascanu "
@@ -43,6 +44,7 @@ def safe_new(x, tag='', dtype=None):
     by gradient, or the R-op to construct new variables for the inputs of
     the inner graph such that there is no interference between the original
     graph and the newly constructed graph.
+
     """
     if hasattr(x, 'name') and x.name is not None:
         nw_name = x.name + tag
@@ -117,21 +119,28 @@ class until(object):
     between the condition and the list of outputs ( unless we enforce and
     order, but since this was not impose up to know it can make quite a bit
     of code to fail).
+
     """
+ 
     def __init__(self, condition):
         self.condition = tensor.as_tensor_variable(condition)
         assert self.condition.ndim == 0
 
 
 def traverse(out, x, x_copy, d, visited=None):
-    ''' Function used by scan to parse the tree and figure out which nodes
-    it needs to replace. There are two options :
+    """
+    Function used by scan to parse the tree and figure out which nodes
+    it needs to replace.
+    
+    There are two options :
         1) x and x_copy or on host, then you would replace x with x_copy
         2) x is on gpu, x_copy on host, then you need to replace
         host_from_gpu(x) with x_copy
-    This happens because initially shared variables are on GPU .. which is
+    This happens because initially shared variables are on GPU... which is
     fine for the main computational graph but confuses things a bit for the
-    inner graph of scan '''
+    inner graph of scan.
+
+    """
     # ``visited`` is a set of nodes that are already known and don't need to be
     # checked again, speeding up the traversal of multiply-connected graphs.
     # if a ``visited`` set is given, it will be updated in-place so the callee
@@ -191,25 +200,25 @@ def clone(output,
           share_inputs=True,
           copy_inputs=DEPRECATED_ARG):
     """
-    Function that allows replacing subgraphs of a computational
-    graph. It returns a copy of the initial subgraph with the corresponding
+    Function that allows replacing subgraphs of a computational graph.
+    
+    It returns a copy of the initial subgraph with the corresponding
     substitutions.
 
-    :type output: Theano Variables (or Theano expressions)
-    :param outputs: Theano expression that represents the computational
-                    graph
+    Parameters
+    ----------
+    output : Theano Variables (or Theano expressions)
+        Theano expression that represents the computational graph.
+    replace : dict
+        Dictionary describing which subgraphs should be replaced by what.
+    share_inputs : bool
+        If True, use the same inputs (and shared variables) as the original
+        graph. If False, clone them. Note that cloned shared variables still
+        use the same underlying storage, so they will always have the same
+        value.
+    copy_inputs
+        Deprecated, use share_inputs.
 
-    :type replace: dict
-    :param replace: dictionary describing which subgraphs should be
-                    replaced by what
-
-    :type share_inputs: bool
-    :param share_inputs: If True, use the same inputs (and shared variables)
-        as the original graph. If False, clone them. Note that cloned
-        shared variables still use the same underlying storage, so they
-        will always have the same value.
-
-    :param copy_inputs: deprecated, use share_inputs.
     """
     if copy_inputs is not DEPRECATED_ARG:
         warnings.warn('In `clone()` function, the argument `copy_inputs` has been deprecated and renamed into `share_inputs`')
@@ -251,7 +260,7 @@ def get_updates_and_outputs(ls):
     """
     This function tries to recognize the updates OrderedDict, the
     list of outputs and the stopping condition returned by the
-    lambda expression and arrange them in a predefined order
+    lambda expression and arrange them in a predefined order.
 
     WRITEME: what is the type of ls? how is it formatted?
             if it's not in the predefined order already, how does
@@ -297,6 +306,7 @@ def get_updates_and_outputs(ls):
 
         Return True iff `x` is made only of lists, tuples, dictionaries, Theano
         variables or `theano.scan_module.until` objects.
+
         """
         # Is `x` a container we can iterate on?
         iter_on = None
@@ -390,10 +400,11 @@ def isNaN_or_Inf_or_None(x):
 
 
 def expand(tensor_var, size):
-    '''
+    """
     Transoforms the shape of a tensor from (d1, d2 ... ) to ( d1+size, d2, ..)
     by adding 0s at the end of the tensor.
-    '''
+
+    """
     # Corner case that I might use in an optimization
     if size == 0:
         return tensor_var
@@ -406,7 +417,7 @@ def expand(tensor_var, size):
 
 
 def equal_computations(xs, ys, in_xs=None, in_ys=None):
-    '''Checks if Theano graphs represent the same computations.
+    """Checks if Theano graphs represent the same computations.
 
     The two lists `xs`, `ys` should have the same number of entries. The
     function checks if for any corresponding pair `(x,y)` from `zip(xs,ys)`
@@ -420,7 +431,7 @@ def equal_computations(xs, ys, in_xs=None, in_ys=None):
     `ys`, but also represent subgraphs of a computational graph in `xs`
     or `ys`.
 
-    '''
+    """
     assert len(xs) == len(ys)
     if in_xs is None:
         in_xs = []
@@ -460,14 +471,16 @@ def equal_computations(xs, ys, in_xs=None, in_ys=None):
     # Explore the two graphs, in parallel, depth first, comparing the nodes
     # along the way for equality.
     def compare_nodes(nd_x, nd_y, common, different):
-        ''' Compare two nodes to determine if they perform equal computation.
+        """
+        Compare two nodes to determine if they perform equal computation.
         This is done by comparing the ops, the number of inputs, outputs and
         by ensuring that the inputs themselves are the result of equal
         computation.
 
         NOTE : This function relies on the variable common to cache
         results to be more efficient.
-        '''
+
+        """
 
         if nd_x.op != nd_y.op:
             return False
@@ -537,13 +550,14 @@ def equal_computations(xs, ys, in_xs=None, in_ys=None):
 
 
 def infer_shape(outs, inputs, input_shapes):
-    '''
-    Compute the shape of the outputs given the shape of the inputs
-    of a theano graph.
+    """
+    Compute the shape of the outputs given the shape of the inputs of a theano
+    graph.
 
     We do it this way to avoid compiling the inner function just to get
     the shape. Changes to ShapeFeature could require changes in this function.
-    '''
+
+    """
     # We use a ShapeFeature because it has all the necessary logic
     # inside.  We don't use the full ShapeFeature interface, but we
     # let it initialize itself with an empty fgraph, otherwise we will
@@ -560,10 +574,10 @@ def infer_shape(outs, inputs, input_shapes):
         shape_feature.set_shape(inp, inp_shp)
 
     def local_traverse(out):
-        '''
+        """
         Go back in the graph, from out, adding computable shapes to shape_of.
-        '''
 
+        """
         if out in shape_feature.shape_of:
             # Its shape is already known
             return
@@ -589,14 +603,18 @@ def infer_shape(outs, inputs, input_shapes):
 
 
 class Validator(object):
-    def __init__(self, valid=None, invalid=None, valid_equivalent=None):
-        '''
-        Check if variables can be expressed without using variables in invalid.
+    """
+    Check if variables can be expressed without using variables in invalid.
+
+    Parameters
+    ----------
+    valid_equivalent
+        Provides a dictionary mapping some invalid variables to valid ones that
+        can be used instead.
 
-        init_valid_equivalent provides a dictionary mapping some invalid
-        variables to valid ones that can be used instead.
-        '''
+    """
 
+    def __init__(self, valid=None, invalid=None, valid_equivalent=None):
         if valid is None:
             valid = []
         if invalid is None:
@@ -616,13 +634,14 @@ class Validator(object):
         self.invalid.update(list(valid_equivalent.keys()))
 
     def check(self, out):
-        '''
+        """
         Go backwards in the graph, from out, and check if out is valid.
 
         If out is a valid node, (out, True) is returned.
         If out is not valid, but has an equivalent e, (e, False) is returned.
         If out is not valid and has no equivalent, None is returned.
-        '''
+
+        """
         if out in self.valid:
             return out, True
         elif out in self.valid_equivalent:
@@ -667,12 +686,13 @@ class Validator(object):
 
 
 def scan_can_remove_outs(op, out_idxs):
-    '''
+    """
     Looks at all outputs defined by indices ``out_idxs`` and see whom can be
     removed from the scan op without affecting the rest. Return two lists,
     the first one with the indices of outs that can be removed, the second
     with the outputs that can not be removed.
-    '''
+
+    """
     non_removable = [o for i, o in enumerate(op.outputs) if i not in
                      out_idxs]
     required_inputs = gof.graph.inputs(non_removable)
@@ -706,7 +726,7 @@ def scan_can_remove_outs(op, out_idxs):
 
 
 def compress_outs(op, not_required, inputs):
-    '''
+    """
     Helpful function that gets a Scan op, a list of indices indicating
     which outputs are not required anymore and should be removed, and
     a list of inputs to the apply node corresponding to the scan op and
@@ -714,7 +734,8 @@ def compress_outs(op, not_required, inputs):
     the indicated outputs are eliminated. Note that eliminating an output
     means removing its inputs from the inner funciton and from the
     node inputs, and changing the dictionary.
-    '''
+
+    """
     info = OrderedDict()
     info['tap_array'] = []
     info['n_seqs'] = op.info['n_seqs']
@@ -852,6 +873,7 @@ def compress_outs(op, not_required, inputs):
 def find_up(l_node, f_node):
     r"""
     Goes up in the graph and returns True if a node in nodes is found.
+
     """
     if isinstance(l_node, gof.Apply):
         l_outs = l_node.outputs
@@ -866,8 +888,9 @@ def reconstruct_graph(inputs, outputs, tag=None):
     """
     Different interface to clone, that allows you to pass inputs.
     Compared to clone, this method always replaces the inputs with
-    new variables of the same type, and returns those ( in the same
+    new variables of the same type, and returns those (in the same
     order as the original inputs).
+
     """
     if tag is None:
         tag = ''
@@ -885,7 +908,11 @@ def reconstruct_graph(inputs, outputs, tag=None):
 
 
 class scan_args(object):
-    """Parses the inputs and outputs of scan in an easy to manipulate format"""
+    """
+    Parses the inputs and outputs of scan in an easy to manipulate format.
+
+    """
+
     def __init__(self, outer_inputs, outer_outputs,
                  _inner_inputs, _inner_outputs, info):
         self.n_steps = outer_inputs[0]
@@ -1070,17 +1097,22 @@ class scan_args(object):
 
 def forced_replace(out, x, y):
     """
-    :param out: Theano Variable
-    :param x: Theano Variable
-    :param y: Theano Variable
-
-    This function checks all internal values of the graph that computes the
-    variable ``out`` for occurances of values identical with ``x``. If such
-    occurances are encountered then they are replaced with variable ``y``.
-    For example:
-        out := sigmoid(wu)*(1-sigmoid(wu))
-        x := sigmoid(wu)
-        forced_replace(out, x, y) := y*(1-y)
+    Check all internal values of the graph that compute the variable ``out``
+    for occurrences of values identical with ``x``. If such occurrences are
+    encountered then they are replaced with variable ``y``.
+    
+    Parameters
+    ----------
+    out : Theano Variable
+    x : Theano Variable
+    y : Theano Variable
+
+    Examples
+    --------
+    out := sigmoid(wu)*(1-sigmoid(wu))
+    x := sigmoid(wu)
+    forced_replace(out, x, y) := y*(1-y)
+
     """
     if out is None:
         return None

theano/scan_module/scan_views.py

 """
-This module provides syntax shortcut for the Scan Op
+This module provides syntax shortcut for the Scan Op.
 
-See scan.py for details on scan
-"""
+See scan.py for details on scan.
 
+"""
 __docformat__ = 'restructedtext en'
 __authors__ = ("Razvan Pascanu "
                "Frederic Bastien "
@@ -37,26 +37,27 @@ def map(fn,
     """
     Similar behaviour as python's map.
 
-    :param fn: The function that ``map`` applies at each iteration step
-               (see ``scan`` for more info).
-
-    :param sequences: List of sequences over which ``map`` iterates
-                      (see ``scan`` for more info).
-
-    :param non_sequences: List of arguments passed to ``fn``. ``map`` will
-                          not iterate over these arguments (see ``scan`` for
-                          more info).
-
-    :param truncate_gradient: See ``scan``.
-
-    :param go_backwards: Boolean value that decides the direction of
-                         iteration. True means that sequences are parsed
-                         from the end towards the begining, while False
-                         is the other way around.
+    Parameters
+    ----------
+    fn
+        The function that ``map`` applies at each iteration step
+        (see ``scan`` for more info).
+    sequences
+        List of sequences over which ``map`` iterates 
+        (see ``scan`` for more info).
+    non_sequences
+        List of arguments passed to ``fn``. ``map`` will not iterate over
+        these arguments (see ``scan`` for more info).
+    truncate_gradient
+        See ``scan``.
+    go_backwards : bool
+        Decides the direction of iteration. True means that sequences are parsed
+        from the end towards the begining, while False is the other way around.
+    mode
+        See ``scan``.
+    name
+        See ``scan``.
 
-    :param mode: See ``scan``.
-
-    :param name: See ``scan``.
     """
     return scan(fn=fn,
                      sequences=sequences,
@@ -77,29 +78,31 @@ def reduce(fn,
            mode=None,
            name=None):
     """
-    Similar behaviour as python's reduce
-
-    :param fn: The function that ``reduce`` applies at each iteration step
-               (see ``scan``  for more info).
-
-    :param sequences: List of sequences over which ``reduce`` iterates
-                      (see ``scan`` for more info)
-
-    :param outputs_info: List of dictionaries describing the outputs of
-                        reduce (see ``scan`` for more info).
-
-    :param non_sequences: List of arguments passed to ``fn``. ``reduce`` will
+    Similar behaviour as python's reduce.
+
+    Parameters
+    ----------
+    fn
+        The function that ``reduce`` applies at each iteration step
+        (see ``scan``  for more info).
+    sequences
+        List of sequences over which ``reduce`` iterates
+        (see ``scan`` for more info).
+    outputs_info
+        List of dictionaries describing the outputs of
+        reduce (see ``scan`` for more info).
+    non_sequences
+        List of arguments passed to ``fn``. ``reduce`` will
                           not iterate over these arguments (see ``scan`` for
                           more info).
+    go_backwards : bool 
+        Decides the direction of iteration. True means that sequences are parsed
+        from the end towards the begining, while False is the other way around.
+    mode
+        See ``scan``.
+    name
+        See ``scan``.
 
-    :param go_backwards: Boolean value that decides the direction of
-                         iteration. True means that sequences are parsed
-                         from the end towards the begining, while False
-                         is the other way around.
-
-    :param mode: See ``scan``.
-
-    :param name: See ``scan``.
     """
     rval = scan(fn=fn,
                      sequences=sequences,
@@ -123,25 +126,27 @@ def foldl(fn,
           mode=None,
           name=None):
     """
-    Similar behaviour as haskell's foldl
-
-    :param fn: The function that ``foldl`` applies at each iteration step
-               (see ``scan`` for more info).
+    Similar behaviour as haskell's foldl.
+
+    Parameters
+    ----------
+    fn
+        The function that ``foldl`` applies at each iteration step
+        (see ``scan`` for more info).
+    sequences
+        List of sequences over which ``foldl`` iterates
+        (see ``scan`` for more info).
+    outputs_info
+        List of dictionaries describing the outputs of reduce
+        (see ``scan`` for more info).
+    non_sequences
+        List of arguments passed to `fn`. ``foldl`` will not iterate over
+        these arguments (see ``scan`` for more info).
+    mode
+        See ``scan``.
+    name
+        See ``scan``.
 
-
-    :param sequences: List of sequences over which ``foldl`` iterates
-                      (see ``scan`` for more info)
-
-    :param outputs_info: List of dictionaries describing the outputs of
-                        reduce (see ``scan`` for more info).
-
-    :param non_sequences: List of arguments passed to `fn`. ``foldl`` will
-                          not iterate over these arguments (see ``scan`` for
-                          more info).
-
-    :param mode: See ``scan``.
-
-    :param name: See ``scan``.
     """
     return reduce(fn=fn,
                   sequences=sequences,
@@ -160,25 +165,27 @@ def foldr(fn,
           mode=None,
           name=None):
     """
-    Similar behaviour as haskell' foldr
-
-    :param fn: The function that ``foldr`` applies at each iteration step
-               (see ``scan`` for more info).
-
-
-    :param sequences: List of sequences over which ``foldr`` iterates
-                      (see ``scan`` for more info)
-
-    :param outputs_info: List of dictionaries describing the outputs of
-                        reduce (see ``scan`` for more info).
-
-    :param non_sequences: List of arguments passed to `fn`. ``foldr`` will
-                          not iterate over these arguments (see ``scan`` for
-                          more info).
-
-    :param mode: See ``scan``.
+    Similar behaviour as haskell' foldr.
+
+    Parameters
+    ----------
+    fn
+        The function that ``foldr`` applies at each iteration step
+        (see ``scan`` for more info).
+    sequences
+        List of sequences over which ``foldr`` iterates
+        (see ``scan`` for more info).
+    outputs_info
+        List of dictionaries describing the outputs of reduce
+        (see ``scan`` for more info).
+    non_sequences
+        List of arguments passed to `fn`. ``foldr`` will not iterate over these
+        arguments (see ``scan`` for more info).
+    mode
+        See ``scan``.
+    name
+        See ``scan``.
 
-    :param name: See ``scan``.
     """
     return reduce(fn=fn,
                   sequences=sequences,