fixing technical stuff in docs

doc/extending/cop.txt

@@ -26,22 +26,24 @@ What needs to be defined
 
 There are less methods to define for an Op than for a Type:
 
-.. function:: c_code(node, name, input_names, output_names, sub)
+.. class:: Op
+
+    .. method:: c_code(node, name, input_names, output_names, sub)
 
       This must return C code that carries the computation we want to do.
 
-.. function:: c_code_cleanup(node, name, input_names, output_names, sub)
+    .. method:: c_code_cleanup(node, name, input_names, output_names, sub)
 
       This must return C code that cleans up whatever c_code allocated and
       that we must free.
 
       *Default:* The default behavior is to do nothing.
 
-.. function:: c_compile_args()
-              c_no_compile_args()
-              c_headers()
-              c_libraries()
-              c_support_code()
+    .. method:: c_compile_args()
+    .. method:: c_no_compile_args()
+    .. method:: c_headers()
+    .. method:: c_libraries()
+    .. method:: c_support_code()
 
       Allows you to specify headers, libraries,
       special g++ arguments to add/exclude or

doc/extending/ctype.txt

@@ -46,35 +46,37 @@ be found in the documentation for :api:`gof.type.Type`. Here, we'll focus on
 the most important ones:
 
 
-.. function:: c_declare(name, sub)
+.. class:: CLinkerType
+
+    .. method:: c_declare(name, sub)
 
         This must return C code which declares variables. These variables
         will be available to operations defined in C. You may also write
         typedefs.
 
-.. function:: c_init(name, sub)
+    .. method:: c_init(name, sub)
 
         This must return C code which initializes the variables declared in
         ``c_declare``. Either this or ``c_extract`` will be called.
 
-.. function:: c_extract(name, sub)
+    .. method:: c_extract(name, sub)
 
         This must return C code which takes a reference to a Python object
         and initializes the variables declared in ``c_declare`` to match the
         Python object's data. Either this or ``c_init`` will be called.
 
-.. function:: c_sync(name, sub)
+    .. method:: c_sync(name, sub)
 
         When the computations are done, transfer the variables from the C
         structure we put them in to the destination Python object. This will
         only be called for the outputs.
 
-.. function:: c_cleanup(name, sub)
+    .. method:: c_cleanup(name, sub)
 
         When we are done using the data, clean up whatever we allocated and
         decrease the appropriate reference counts.
 
-.. function:: c_compile_args()
+    .. method:: c_compile_args()
                   c_no_compile_args()
                   c_headers()
                   c_libraries()
@@ -391,7 +393,7 @@ done. Note which variables get extracted (the three inputs ``x``, ``y`` and
 output ``b``) and which one is synced (the final output ``b``).
 
 The C code above is a single C block for the whole graph. Depending on
-which :ref:`linker` is used to process the computation graph, it is
+which :term:`linker` is used to process the computation graph, it is
 possible that one such block is generated for each operation and that
 we transit through Python after each operation. In that situation,
 ``a`` would be synced by the addition block and extracted by the

doc/extending/graphstructures.txt

@@ -146,7 +146,7 @@ Automatic wrapping
 
 All nodes in the graph must be instances of ``Apply`` or ``Result``, but
 ``<Op subclass>.make_node()`` typically wraps constants to satisfy those
-constraints. For example, the :api:`tensor.add <theano.tensor.basic.add>`
+constraints. For example, the :func:`tensor.add`
 Op instance is written so that:
 
 .. code-block:: python
@@ -189,8 +189,8 @@ An *Apply node* is a type of internal node used to represent a
 manipulated directly by the end user. They may be accessed via
 a Variable's ``owner`` field.
 
-An Apply node is typically an instance of the :api:`Apply
-<theano.gof.graph.Apply>` class. It represents the application
+An Apply node is typically an instance of the :class:`Apply`
+class. It represents the application
 of an :ref:`op` on one or more inputs, where each input is a
 :ref:`variable`. By convention, each Op is responsible for
 knowing how to build an Apply node from a list of
@@ -215,8 +215,7 @@ An Apply instance has three important fields:
   A list of :ref:`Variables <variable>` that represent the return values
   of the function.
 
-An Apply instance can be created by calling ``gof.Apply(op, inputs,
-outputs)``.
+An Apply instance can be created by calling ``gof.Apply(op, inputs, outputs)``.
 
 
 
@@ -260,7 +259,7 @@ Type
 A :ref:`type` in Theano represents a set of constraints on potential
 data objects. These constraints allow Theano to tailor C code to handle
 them and to statically optimize the computation graph. For instance,
-the :ref:`irow <predefinedtypes>` type in the ``theano.tensor`` package
+the :ref:`irow <libdoc_tensor_creation>` type in the ``theano.tensor`` package
 gives the following constraints on the data the Variables of type ``irow``
 may contain:
 
@@ -273,8 +272,8 @@ that declares the right data types and that contains the right number
 of loops over the dimensions.
 
 Note that a Theano :ref:`type` is not equivalent to a Python type or
-class. Indeed, in Theano, :ref:`irow <predefinedtypes>` and :ref:`dmatrix
-<predefinedtypes>` both use ``numpy.ndarray`` as the underlying type
+class. Indeed, in Theano, :ref:`irow <libdoc_tensor_creation>` and :ref:`dmatrix
+<libdoc_tensor_creation>` both use ``numpy.ndarray`` as the underlying type
 for doing computations and storing data, yet they are different Theano
 Types. Indeed, the constraints set by ``dmatrix`` are:
 
@@ -311,8 +310,7 @@ Variables. For example, when I type
 >>> x = theano.tensor.ivector()
 >>> y = -x
 
-``x`` and ``y`` are both Variables, i.e. instances of the :api:`Variable
-<theano.gof.graph.Variable>` class. The :ref:`type` of both ``x`` and
+``x`` and ``y`` are both Variables, i.e. instances of the :class:`Variable` class. The :ref:`type` of both ``x`` and
 ``y`` is ``theano.tensor.ivector``.
 
 Unlike ``x``, ``y`` is a Variable produced by a computation (in this
@@ -324,7 +322,7 @@ through ``y.owner``.
 
 More specifically, a Variable is a basic structure in Theano that
 represents a datum at a certain point in computation. It is typically
-an instance of the class :api:`Variable <theano.gof.graph.Variable>` or
+an instance of the class :class:`Variable` or
 one of its subclasses.
 
 A Variable ``r`` contains four important fields:
@@ -365,6 +363,7 @@ any circumstances modify the input. This means that a constant is
 eligible to participate in numerous optimizations: constant inlining
 in C code, constant folding, etc.
 
-A constant does not need to be specified in a :ref:`function`'s list
+A constant does not need to be specified in a :func:`function
+<function.function>`'s list
 of inputs.  In fact, doing so will raise an exception.
 

doc/extending/op.txt

@@ -12,7 +12,7 @@ computations. We'll start by defining multiplication.
 Op's contract
 =============
 
-An Op (:api:`gof.op.Op`) is any object which defines the
+An Op (:class:`gof.Op`) is any object which defines the
 following methods:
 
 
@@ -134,9 +134,7 @@ following methods:
   includes this Op.
 
 
-For each method, the *default* is what :api:`theano.gof.op.Op` defines
-for you.  At a bare minimum, a new Op must define ``make_node`` and
-``perform``, which have no defaults.
+At a bare minimum, a new Op must define ``make_node`` and ``perform``, which have no defaults.
 
 For more details, including the interface for providing a C
 implementation of ``perform()``, refer to the documentation for :ref:`op`.

doc/extending/optimization.txt

@@ -139,7 +139,7 @@ simplification described above:
 
 Here's how it works: first, in ``add_requirements``, we add the
 ``ReplaceValidate`` :ref:`envfeature` located in
-:api:`theano.gof.toolbox`. This feature adds the ``replace_validate``
+:ref:`libdoc_gof_toolbox`. This feature adds the ``replace_validate``
 method to ``env``, which is an enhanced version of ``replace`` that
 does additional checks to ensure that we are not messing up the
 computation graph (note: if ``ReplaceValidate`` was already added by
@@ -305,7 +305,7 @@ Theano defines some shortcuts to make LocalOptimizers:
 .. function:: PatternSub(pattern1, pattern2)
 
   Replaces all occurrences of the first pattern by the second pattern.
-  See :api:`theano.gof.opt.PatternSub`.
+  See :class:`PatternSub`.
 
 
 .. code-block:: python
@@ -342,7 +342,7 @@ or ``PatternSub``, it is highly recommended to use them.
 
 WRITEME: more about using PatternSub (syntax for the patterns, how to
 use constraints, etc. - there's some decent doc at
-:api:`theano.gof.opt.PatternSub` for those interested)
+:class:`PatternSub` for those interested)
 
 
 
@@ -376,8 +376,8 @@ Definition of optdb
 -------------------
 
 optdb is an object which is an instance of
-:api:`theano.gof.SequenceDB <theano.gof.optdb.SequenceDB>`,
-itself a subclass of :api:`theano.gof.DB <theano.gof.optdb.DB>`.
+:class:`SequenceDB <optdb.SequenceDB>`,
+itself a subclass of :class:`DB <optdb.DB>`.
 There exist (for now) two types of DB, SequenceDB and EquilibriumDB.
 When given an appropriate Query, DB objects build an Optimizer matching
 the query.
@@ -399,7 +399,7 @@ well and the LocalOptimizers they return will be put in their places
 (note that as of yet no DB can produce LocalOptimizer objects, so this
 is a moot point).
 
-Theano contains one principal DB object, :api:`theano.gof.optdb`, which
+Theano contains one principal DB object, :ref:`libdoc.gof.optdb`, which
 contains all of Theano's optimizers with proper tags. It is
 recommended to insert new Optimizers in it. As mentioned previously,
 optdb is a SequenceDB, so, at the top level, Theano applies a sequence
@@ -411,28 +411,30 @@ Query
 
 A Query is built by the following call:
 
-::
+.. code-block:: python
 
    theano.gof.Query(include, require = None, exclude = None, subquery = None)
 
-.. attribute:: include
+.. class:: Query
+
+    .. attribute:: include
 
        A set of tags (a tag being a string) such that every
        optimization obtained through this Query must have **one** of the tags
        listed. This field is required and basically acts as a starting point
        for the search.
 
-.. attribute:: require
+    .. attribute:: require
 
        A set of tags such that every optimization obtained
        through this Query must have **all** of these tags.
 
-.. attribute:: exclude
+    .. attribute:: exclude
 
        A set of tags such that every optimization obtained
        through this Query must have **none** of these tags.
 
-.. attribute:: subquery
+    .. attribute:: subquery
 
        optdb can contain sub-databases; subquery is a
        dictionary mapping the name of a sub-database to a special Query.

doc/extending/type.txt

@@ -22,7 +22,9 @@ i.e.  the same default argument names and values. If you wish to add
 extra arguments to any of these methods, these extra arguments must have
 default values.
 
-.. function:: filter(value, strict=False)
+.. class:: PureType
+
+    .. method:: filter(value, strict=False)
 
       This casts a value to match the Type and returns the
       casted value. If ``value`` is incompatible with the Type,
@@ -33,7 +35,7 @@ default values.
       must be called ``strict`` (Theano often calls it by keyword) and must
       have a default value of ``False``.
 
-.. function:: is_valid_value(value)
+    .. method:: is_valid_value(value)
 
       Returns True iff the value is compatible with the Type. If
       ``filter(value, strict = True)`` does not raise an exception, the
@@ -42,20 +44,20 @@ default values.
       *Default:* True iff ``filter(value, strict = True)`` does not raise
       an exception.
 
-.. function:: values_eq(a, b)
+    .. method:: values_eq(a, b)
 
       Returns True iff ``a`` and ``b`` are equal.
 
       *Default:* ``a == b``
 
-.. function:: values_eq_approx(a, b)
+    .. method:: values_eq_approx(a, b)
 
       Returns True iff ``a`` and ``b`` are approximately equal, for a
       definition of "approximately" which varies from Type to Type.
 
       *Default:* ``values_eq(a, b)``
 
-.. function:: make_variable(name=None)
+    .. method:: make_variable(name=None)
 
       Makes a :term:`Variable` of this Type with the specified name, if
       ``name`` is not ``None``. If ``name`` is ``None``, then the Variable does
@@ -66,19 +68,19 @@ default values.
       Variable's ``type`` will be the object that defines this method (in
       other words, ``self``).
 
-.. function:: __call__(name=None)
+    .. method:: __call__(name=None)
 
       Syntactic shortcut to ``make_variable``.
 
       *Default:* ``make_variable``
 
-.. function:: __eq__(other)
+    .. method:: __eq__(other)
 
       Used to compare Type instances themselves
 
       *Default:* ``object.__eq__``
 
-.. function:: __hash__()
+    .. method:: __hash__()
 
       Types should not be mutable, so it should be OK to define a hash
       function.  Typically this function should hash all of the terms

doc/glossary.txt

@@ -13,37 +13,12 @@ Glossary of terminology
 
     Broadcasting
         Broadcasting is a mechanism which allows tensors with
-        different numbers of dimensions to be added or multiplied
-        together by (virtually) replicating the smaller tensor along
+        different numbers of dimensions to be used in element-by-element
+        (elementwise) computations.  It works by
+        (virtually) replicating the smaller tensor along
         the dimensions that it is lacking.  
         
-        In a nutshell, broadcasting is the mechanism by which a scalar
-        may be added to a matrix, a vector to a matrix or a scalar to
-        a vector.
-
-        .. figure:: bcast.png
-
-           Broadcasting a row matrix. T and F respectively stand for
-           True and False and indicate along which dimensions we allow
-           broadcasting.
-
-           If the second argument were a vector, its shape would be
-           ``(2,)`` and its broadcastable pattern ``(F,)``. They would
-           be automatically expanded to the **left** to match the
-           dimensions of the matrix (adding ``1`` to the shape and ``T``
-           to the pattern), resulting in ``(1, 2)`` and ``(T, F)``.
-           It would then behave just like the example above.
-
-
-        Unlike numpy which does broadcasting dynamically, Theano needs
-        to know, for any operation which supports broadcasting, which
-        dimensions will need to be broadcasted. When applicable, this
-        information is given in the :term:`Type` of a :term:`Variable`.
-
-        See also:
-
-        * :ref:`How broadcasting is used in Theano's tensor types <tensortypes>`
-
+        For more detail, see :ref:`libdoc_tensor_broadcastable`, and also
         * `SciPy documentation about numpy's broadcasting <http://www.scipy.org/EricsBroadcastingDoc>`_
         * `OnLamp article about numpy's broadcasting <http://www.onlamp.com/pub/a/python/2000/09/27/numerically.html>`_
 
@@ -79,6 +54,9 @@ Glossary of terminology
         others. These operations are all instances of :api:`Elemwise
         <theano.tensor.elemwise.Elemwise>`.
 
+    Expression
+        See :term:`Apply`
+
     Expression Graph
         A directed, acyclic set of connected :term:`Variable` and
         :term:`Apply` nodes that express symbolic functional relationship
@@ -89,7 +67,6 @@ Glossary of terminology
         :term:`Type`, or read more about :ref:`tutorial_graphstructures`.
 
     Destructive
-
         An :term:`Op` is destructive (of particular input[s]) if its
         computation requires that one or more inputs be overwritten or
         otherwise invalidated.  For example, :term:`inplace` Ops are
@@ -110,13 +87,24 @@ Glossary of terminology
         Inplace computations are computations that destroy their inputs as a
         side-effect.  For example, if you iterate over a matrix and double
         every element, this is an inplace operation because when you are done,
-        the original input has been overwritten.
+        the original input has been overwritten.  Ops representing inplace
+        computations are :term:`destructive`, and by default these can only be
+        inserted by optimizations, not user code.
+
+    Linker
+        Part of a function :term:`Mode` -- an object responsible for 'running'
+        the compiled function.  Among other things, the linker determines whether computations are carried out with C or Python code.
         
     Merge
         A simple optimization in which redundant :term:`Apply` nodes are
         combined.  For example, in ``function([x,y], [(x+y)*2, (x+y)*3])`` the merge
         optimization will ensure that ``x`` and ``y`` are only added once.
 
+    Mode 
+        An object providing an :term:`optimizer` and a :term:`linker` that is
+        passed to :term:`theano.funcion`.  It parametrizes how an expression
+        graph is converted to a callable object.
+
     Op
         The ``.op`` of an :term:`Apply`, together with its symbolic inputs
         fully determines what kind of computation will be carried out for that
@@ -128,13 +116,18 @@ Glossary of terminology
         See also :term:`Variable`, :term:`Type`, and :term:`Apply`, 
         or read more about :ref:`tutorial_graphstructures`.
 
-    Expression
-        See :term:`Apply`
+    Optimizer
+        An instance of :class:`Optimizer`, which has the capacity to provide
+        :term:`optimization`s.
+
+    Optimization
+        A :term:`graph` transformation applied by an :term:`optimizer` during
+        the compilation of a :term:`graph` by :term:`theano.function`.
 
     Storage
         The memory that is used to store the value of a Variable.  In most
         cases storage is internal to a compiled function, but in some cases
-        (such as :term:`constant` and :term:`<shared variable>` the storage is not internal.
+        (such as :term:`constant` and :term:`shared variable <shared variable>` the storage is not internal.
 
     Shared Variable
         A :term:`Variable` whose value may be shared between multiple functions.  See :func:`shared` and :func:`theano.function <function.function>`.

doc/library/tensor/basic.txt

@@ -168,32 +168,27 @@ bytes, we would do:
 Shared Variable
 ---------------
 
-Yet another way of creating a special type of Theano variable is by using
-:func:`shared` as in the example below:
+Another way of creating a TensorVariable (a TensorSharedVariable to be
+precise) is by calling :func:`shared()`
 
 .. code-block:: python
 
-  x = shared(value, name)
+  x = shared(numpy.random.randn(3,4))
 
-Shared takes two parameters, `value` and `name` and creates a Theano 
-variable with the name `name` and initial value `value`. The type of this
-variable is obtained from the type of the value `value`, so if value is a
-numpy float matrix the shared variable will be of type `fmatrix`. 
+This will return a :term:`shared variable <shared variable>` whose ``.value`` is
+a numpy ndarray.  The number of dimensions and dtype of the Variable are
+inferred from the ndarray argument.
 
-Note that a shared variable is not like other Theano variables. For more
-details of how to use shared variables look :ref:`here <functionstateexample>` (or for more details
-:ref:`here <sharedvars>`). TODO : make the last link to a detailed
-description of shared variables.
+For additional information, see the :func:`shared` documentation.
 
 
 Autocasting
 -----------
 
- Theano does autocasting of numpy ndarray or python floats/ints into 
- Theano constants.
+Theano does autocasting of python floats/ints into Theano constants.
 
-TODO: What does (or compatible) mean?  Talk about casting rules, refer .
-TODO: link to floatX (?) 
+.. TODO: What does (or compatible) mean?  Talk about casting rules, refer .
+.. TODO: link to floatX (?) 
 
 .. function:: as_tensor_variable(x, ...)
 
@@ -438,8 +433,6 @@ information is given in the :ref:`type` of a *Variable*.
 
 See also:
 
-* :ref:`How broadcasting is used in Theano's tensor types <tensortypes>`
-
 * `SciPy documentation about numpy's broadcasting <http://www.scipy.org/EricsBroadcastingDoc>`_
 
 * `OnLamp article about numpy's broadcasting <http://www.onlamp.com/pub/a/python/2000/09/27/numerically.html>`_

doc/tutorial/debug_faq.txt

@@ -130,19 +130,14 @@ This is actually so simple the debugging could be done easily, but it's for
 illustrative purposes. As the matrices can't be element-wise multiplied
 (unsuitable shapes), we get the following exception:
 
-::
+.. code-block:: text
+
     File "ex.py", line 14, in <module>
       f(mat1, mat2)
-    File "/u/username/Theano/theano/compile/function_module.py", line 451, in
- __call__
-    File "/u/username/Theano/theano/gof/link.py", line 271, in
- streamline_default_f
-    File "/u/username/Theano/theano/gof/link.py", line 267, in
- streamline_default_f
-    File "/u/username/Theano/theano/gof/cc.py", line 1049, in execute
-  ValueError: ('Input dimension mis-match. (input[0].shape[0] = 3,
- input[1].shape[0] = 5)',
-       Elemwise{mul,no_inplace}(a, b), Elemwise{mul,no_inplace}(a, b))
+    File "/u/username/Theano/theano/compile/function_module.py", line 451, in __call__
+    File "/u/username/Theano/theano/gof/link.py", line 271, in streamline_default_f
+    File "/u/username/Theano/theano/gof/link.py", line 267, in streamline_default_f
+    File "/u/username/Theano/theano/gof/cc.py", line 1049, in execute ValueError: ('Input dimension mis-match. (input[0].shape[0] = 3, input[1].shape[0] = 5)', Elemwise{mul,no_inplace}(a, b), Elemwise{mul,no_inplace}(a, b))
 
 The call stack contains a few useful informations to trace back the source
 of the error. There's the script where the compiled function was called --
@@ -160,7 +155,8 @@ dimensions of the matrices involved, but for the sake of example say we'd
 need the other dimensions to pinpoint the error. First, we re-launch with
 the debugger module and run the program with "c":
 
-::
+.. code-block:: text
+
     python -m pdb ex.py
     > /u/username/experiments/doctmp1/ex.py(1)<module>()
     -> import theano
@@ -169,12 +165,10 @@ the debugger module and run the program with "c":
 Then we get back the above error printout, but the interpreter breaks in
 that state. Useful commands here are
 
-* "up" and "down" (to move up and down the call stack),</li>
-* "l" (to print code around the line in the current stack position),</li>
-* "p variable_name" (to print the string representation of
-'variable_name'),</li>
-* "p dir(object_name)", using the Python dir() function to print the list of
-an object's members
+* "up" and "down" (to move up and down the call stack),
+* "l" (to print code around the line in the current stack position),
+* "p variable_name" (to print the string representation of 'variable_name'),
+* "p dir(object_name)", using the Python dir() function to print the list of an object's members
 
 Here, for example, I do "up", and a simple "l" shows me there's a local
 variable "node". This is the "node" from the computation graph, so by

doc/tutorial/symbolic_graphs.txt

 
-.. _symbolic_graph:
+.. _tutorial_graphstructures:
 
 ================
 Graph Structures
@@ -77,7 +77,7 @@ Optimizations
 =============
 
 When compiling a Theano function, what you give to the
-:ref:`theano.function <libdoc_compile_function>` is actually a graph
+:func:`theano.function <function.function>` is actually a graph
 (starting from the outputs variables you can traverse the graph up to
 the input variables). While this graph structure shows how to compute
 the output from the input, it also offers the posibility to improve the