splitted some topics into advanced, updated advanced tutorial

doc/advanced_tutorial/constype.txt

-
-
-====================
-Making the cons type
-====================
-
-WRITEME

doc/advanced_tutorial/cop.txt

@@ -26,22 +26,24 @@ What needs to be defined
 
 There are less methods to define for an Op than for a Type:
 
-- **c_code(node, name, input_names, output_names, sub)**
+.. function:: c_code(node, name, input_names, output_names, sub)
 
-  - This must return C code that carries the computation we want to
-    do.
+  This must return C code that carries the computation we want to do.
 
-- **c_code_cleanup(node, name, input_names, output_names, sub)**
+.. function:: 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.
+  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.
+  *Default* The default behavior is to do nothing.
 
-- **c_compile_args(), c_headers(), c_libraries(), c_support_code()**
+.. function:: c_compile_args()
+              c_headers()
+              c_libraries()
+              c_support_code()
 
-  - Allows you to specify headers, libraries, special g++ arguments or
-    helper functions/structs that the type needs. See :ref:`op`.
+  Allows you to specify headers, libraries, special g++ arguments or
+  helper functions/structs that the type needs. See :ref:`op`.
 
 
 The ``name`` argument is currently given an invalid value, so steer

doc/advanced_tutorial/ctype.txt

@@ -46,38 +46,41 @@ be found in the documentation for :ref:`type`. Here, we'll focus on
 the most important ones:
 
 
-- **c_declare(name, sub)**
+.. function:: 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.
+  This must return C code which declares variables. These variables
+  will be available to operations defined in C. You may also write
+  typedefs.
 
-- **c_init(name, sub)**
+.. function:: 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.
+  This must return C code which initializes the variables declared in
+  c_declare. Either this or c_extract will be called.
 
-- **c_extract(name, sub)**
+.. function:: 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.
+  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.
 
-- **c_sync(name, sub)**
+.. function:: 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.
+  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.
 
-- **c_cleanup(name, sub)**
+.. function:: c_cleanup(name, sub)
 
-  - When we are done using the data, clean up whatever we allocated
-    and decrease the appropriate reference counts.
+  When we are done using the data, clean up whatever we allocated and
+  decrease the appropriate reference counts.
 
-- **c_compile_args(), c_headers(), c_libraries(), c_support_code()**
+.. function:: c_compile_args()
+              c_headers()
+              c_libraries()
+              c_support_code()
 
-  - Allows you to specify headers, libraries, special g++ arguments or
-    helper functions/structs that the type needs. See :ref:`type`.
+  Allows you to specify headers, libraries, special g++ arguments or
+  helper functions/structs that the type needs. See :ref:`type`.
 
 
 Each of these functions take two arguments, ``name`` and ``sub`` which

doc/advanced_tutorial/index.txt

@@ -24,7 +24,7 @@ grounding for fundamental Theano concepts.
 
 .. toctree::
 
-   theano_vs_python
+   theano_vs_c
    graphstructures
    type
    op

doc/advanced_tutorial/optimization.txt

@@ -38,24 +38,24 @@ Global optimization
 A global optimization (or optimizer) is an object which defines the following
 methods:
 
-- **apply(env)**
+.. function:: apply(env)
 
-  - This method takes an Env object which contains the computation
-    graph and does modifications in line with what the optimization is
-    meant to do. This is of the main method of the optimizer.
+  This method takes an Env object which contains the computation graph
+  and does modifications in line with what the optimization is meant
+  to do. This is of the main method of the optimizer.
 
-- **add_requirements(env)**
+.. function:: add_requirements(env)
 
-  - This method takes an Env object and adds :ref:`features
-    <envfeature>` to it. These features are "plugins" that are needed
-    for the apply method to do its job properly.
+  This method takes an Env object and adds :ref:`features
+  <envfeature>` to it. These features are "plugins" that are needed
+  for the apply method to do its job properly.
 
-- **optimize(env)**
+.. function:: optimize(env)
 
-  - This is the interface function called by Theano.
+  This is the interface function called by Theano.
 
-  - *Default:* this is defined by Optimizer as ``add_requirement(env);
-    apply(env)``.
+  *Default:* this is defined by Optimizer as ``add_requirement(env);
+  apply(env)``.
 
 See the section about :ref:`env` to understand how to define these
 methods.
@@ -66,14 +66,14 @@ Local optimization
 
 A local optimization is an object which defines the following methods:
 
-- **transform(node)**
+.. function:: transform(node)
 
-  - This method takes an :ref:`apply` node and returns either False to
-    signify that no changes are to be done or a list of Variables which
-    matches the length of the node's ``outputs`` list. When the
-    LocalOptimizer is applied by a Navigator, the outputs of the node
-    passed as argument to the LocalOptimizer will be replaced by the
-    list returned.
+  This method takes an :ref:`apply` node and returns either False to
+  signify that no changes are to be done or a list of Variables which
+  matches the length of the node's ``outputs`` list. When the
+  LocalOptimizer is applied by a Navigator, the outputs of the node
+  passed as argument to the LocalOptimizer will be replaced by the
+  list returned.
 
 
 
@@ -380,21 +380,21 @@ A Query is built by the following call:
 
 theano.gof.Query(include, require = None, exclude = None, subquery = None)
 
-  * **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.
+**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.
 
-  * **require**: a set of tags such that every optimization obtained
-    through this Query must have **all** of these tags.
+**require**: a set of tags such that every optimization obtained
+through this Query must have **all** of these tags.
 
-  * **exclude**: a set of tags such that every optimization obtained
-    through this Query must have **none** of these tags.
+**exclude**: a set of tags such that every optimization obtained
+through this Query must have **none** of these tags.
 
-  * **subquery**: optdb can contain sub-databases; subquery is a
-    dictionary mapping the name of a sub-database to a special Query.
-    If no subquery is given for a sub-database, the original Query
-    will be used again.
+**subquery**: optdb can contain sub-databases; subquery is a
+dictionary mapping the name of a sub-database to a special Query.  If
+no subquery is given for a sub-database, the original Query will be
+used again.
 
 Furthermore, a Query object includes three methods, ``including``,
 ``requiring`` and ``excluding`` which each produce a new Query object
@@ -454,8 +454,8 @@ Theano defines two EquilibriumDBs where you can put local
 optimizations:
 
 
-* **canonicalize**: this contains optimizations that aim to *simplify*
-  the graph:
+**canonicalize**: this contains optimizations that aim to *simplify*
+the graph:
 
   * Replace rare or esoterical operations with their equivalents using
     elementary operations.
@@ -467,8 +467,8 @@ optimizations:
   * Fold constants (Constant(2)*Constant(2) becomes Constant(4))
 
 
-* **specialize**: this contains optimizations that aim to *specialize*
-  the graph:
+**specialize**: this contains optimizations that aim to *specialize*
+the graph:
 
   * Replace a combination of operations with a special operation that
     does the same thing (but better).

doc/advanced_tutorial/theano_vs_python.txt → doc/advanced_tutorial/theano_vs_c.txt

 
-.. _theano_vs_python:
+.. _theano_vs_c:
 
-======================
-Theano vs. Python
-======================
+============
+Theano vs. C
+============
 
 We describe some of the patterns in Theano, and present their closest
-analogue in Python:
+analogue in a statically typed language such as C:
 
 =============== ===========================================================
-Theano          Python
+Theano          C
 =============== ===========================================================
 Apply           function application / function call
 Variable          function data / variable
@@ -17,3 +17,25 @@ Op              operations carried out in computation / function definition
 Type            data types
 Module          ??? class?
 =============== ===========================================================
+
+For example:
+
+.. code-block:: c
+
+   int main(int a) {
+       int b = 3;
+       int c = f(b)
+       return g(a, c);
+   }
+
+
+Based on this code snippet, we can relate f and g to Ops, a, b and c
+to Variables, g(a, c) and f(b) (taken as meaning the action of
+computing f or g on their respective inputs) to Applies. Lastly, int
+could be interpreted as the Theano Type of the Variables a and b.
+
+
+
+
+
+

doc/advanced_tutorial/type.txt

@@ -22,69 +22,69 @@ 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.
 
-- **filter(value, strict=False)**
+.. function:: filter(value, strict=False)
 
-  - This casts a value to match the Type and returns the
-    casted value. If ``value`` is incompatible with the Type,
-    the method must raise an exception. If ``strict`` is True, ``filter`` must return a
-    reference to ``value`` (i.e. casting prohibited)
+  This casts a value to match the Type and returns the
+  casted value. If ``value`` is incompatible with the Type,
+  the method must raise an exception. If ``strict`` is True, ``filter`` must return a
+  reference to ``value`` (i.e. casting prohibited)
 
-    We need to define ``filter`` with two arguments. The second argument
-    must be called ``strict`` (Theano often calls it by keyword) and must
-    have a default value of ``False``.
+  We need to define ``filter`` with two arguments. The second argument
+  must be called ``strict`` (Theano often calls it by keyword) and must
+  have a default value of ``False``.
 
-- **is_valid_value(value)**
+.. function:: 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
-    value is compatible with the Type.
+  Returns True iff the value is compatible with the Type. If
+  ``filter(value, strict = True)`` does not raise an exception, the
+  value is compatible with the Type.
 
-  - *Default*: True iff ``filter(value, strict = True)`` does not raise an
-    exception.
+  *Default*: True iff ``filter(value, strict = True)`` does not raise
+  an exception.
 
-- **values_eq(a, b)**
+.. function:: values_eq(a, b)
 
-  - Returns True iff ``a`` and ``b`` are equal.
+  Returns True iff ``a`` and ``b`` are equal.
 
-  - *Default*: ``a == b``
+  *Default*: ``a == b``
 
-- **values_eq_approx(a, b)**
+.. function:: 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.
+  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)``
+  *Default*: ``values_eq(a, b)``
 
-- **make_variable(name=None)**
+.. function:: 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
-    not have a name. The Variable will have its ``type`` field set to the
-    Type object.
+  Makes a :term:`Variable` of this Type with the specified name, if
+  ``name is not None``. If ``name is ``None``, then the Variable does
+  not have a name. The Variable will have its ``type`` field set to
+  the Type object.
 
-  - *Default*: there is a generic definition of this in Type. The Variable's
-    ``type`` will be the object that defines this method (in other words,
-    ``self``).
+  *Default*: there is a generic definition of this in Type. The
+  Variable's ``type`` will be the object that defines this method (in
+  other words, ``self``).
 
-- **__call__(name=None)**:
+.. function:: __call__(name=None)
 
-  - Syntactic shortcut to ``make_variable``.
+  Syntactic shortcut to ``make_variable``.
 
-  - *Default*: ``make_variable``
+  *Default*: ``make_variable``
 
-- **__eq__(self, other)**:
+.. function:: __eq__(other)
 
-  - Used to compare Type instances themselves
+  Used to compare Type instances themselves
 
-  - *Default*: ``object.__eq__``
+  *Default*: ``object.__eq__``
 
-- **__hash__(self)**:
+.. function:: __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 involved in ``__eq__``.
+  Types should not be mutable, so it should be Ok to define a hash
+  function.  Typically this function should hash all of the terms
+  involved in ``__eq__``.
 
-  - *Default*: ``id(self)``
+  *Default*: ``id(self)``
 
 For each method, the *default* is what ``Type`` defines
 for you. So, if you create an instance of ``Type`` or an

doc/basic_tutorial/index.txt

@@ -30,6 +30,5 @@ Now we're ready for the tour:
 
    adding
    examples
-   function
    module
    tools

doc/contents.txt

@@ -8,12 +8,14 @@ Contents
 .. toctree::
    :maxdepth: 2
 
-   LICENSE
+   index
    introduction
+   LICENSE
    install
    basic_tutorial/index
    advanced_tutorial/index
    topics/index
+   advanced/index
    indexes/index
    glossary
    links

doc/install.txt

@@ -144,9 +144,9 @@ Generating the documentation
 ----------------------------
 
 You can read the latest HTML documentation `here
-<http://pylearn.org/theano/contents.html>`_.
+<http://pylearn.org/theano/contents.html>`__.
 You can download the latest PDF documentation `here
-<http://pylearn.org/theano/theano.pdf`_.
+<http://pylearn.org/theano/theano.pdf`__.
 
 We recommend you look at the documentation on the website, since it
 will be more current than the documentation included with the package.

doc/basic_tutorial/function.txt → doc/topics/function.txt

 
-.. _function:
+.. _usingfunction:
 
-===============
-theano.function
-===============
+=====================
+Using theano.function
+=====================
 
 
 This page is about ``theano.function``, the interface for compiling graphs into callable objects.

doc/topics/index.txt

 
-.. _advanced:
+.. _topics:
 
-===============
-Advanced Topics
-===============
+======
+Topics
+======
 
 .. toctree::
     :maxdepth: 2
    
+    function
     pipeline
+    unittest
     profilemode
     debugmode
+    debug_faq
     module_vs_op
     randomstreams
 
-
-.. env
-.. features
-.. optimization
-.. compilation
-.. ccodegen
-.. function
-.. module