rewrote index page and added a link to oplist and typelist for use with :ref:,…

doc/doc/glossary.txt → doc/glossary.txt

@@ -6,30 +6,132 @@ Glossary of terminology
 .. glossary::
 
     Apply
-        Op-related graph node (expression instance)
-        
-        An Apply instance (`Apply API <http://lgcm.iro.umontreal.ca/epydoc/theano.gof.graph.Apply-class.html>`_)
-        represents the application of an :term:`Op` on input :term:`Results <Result>`, producing output :term:`Results <Result>`.
-        Users typically do not instantiate Apply directly, instead they should use an Op's ``make_node`` or ``__call__`` function.
-        
-        Comparing with the Python language, an :term:`Apply` instance is theano's version of a function call (or expression instance) whereas :term:`Op` is theano's version of a function definition.
-        
-        An Apply instance serves as a simple structure with three important fields:
-          ``inputs``: a list of :term:`Result` instances that represent the arguments of the function.
-          ``outputs``: a list of :term:`Result` instances that represent the return values of the function.
-          ``op``: an Op instance that determines the function/transformation being applied here.
+        WRITEME
+
+    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
+        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.
         
-        Theano.function uses the Apply instances' ``inputs`` field together with each :term:`Result`'s ``owner`` field to determine which inputs are necessary to compute the function's outputs.
-        Theano.function uses the Apply instances' ``op`` field to know how to compute the intermediate and final Results.
+        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:`Result`.
+
+        For more information, see the article about broadcasting_.
         
-    Broadcasting
-        implicit tensor repmat
+        See 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>`_
+
+    constant
+        WRITEME
+
+    elementwise
+        An elementwise operation ``f`` on two matrices ``M`` and ``N``
+        is one such that:
         
+        ``f(M, N)[i, j] = f(M[i, j], N[i, j])``
+
+        In other words, each element of an input matrix is combined
+        with the corresponding element of the other(s). There are no
+        dependencies between elements whose ``[i, j]`` coordinates do
+        not correspond, so an elementwise operation is like a scalar
+        operation generalized along several dimensions.
+
+        There exist unary, binary, ternary, etc. elementwise
+        operations and they can work on scalars, vectors, matrices,
+        etc. as long as all the inputs have the same dimensions or can
+        be :term:`broadcasted <broadcasting>` to the same dimensions.
+
+        Examples of elementwise operations in Theano: ``add, sub, mul,
+        div, neg, inv, log, exp, sin, cos, tan`` and many
+        others. These operations are all subclasses of :api:`Elemwise
+        <theano.tensor.elemwise.Elemwise>`.
+
+    graph
         WRITEME
+
+    op
+        WRITEME
+
+    Result 
+        A :ref:`result` is the main data structure you work with when
+        using Theano. The symbolic inputs that you operate on are
+        Results and what you get from applying various operations to
+        these inputs are also Results. For example, when I type
+
+        >>> x = theano.tensor.ivector()
+        >>> y = -x
+
+        ``x`` and ``y`` are both Results, i.e. instances of the
+        :api:`Result <theano.gof.graph.Result>` class. The
+        :term:`Type` of both ``x`` and ``y`` is
+        ``theano.tensor.ivector``.
+
+        For more information, see: :ref:`result`.
+
+    type
+        WRITEME
+
+
+.. _broadcasting: concepts/broadcasting.html
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+..
+    Apply
+        TRANSFERRED
         
-        The following pages appear to describe broadcasting, but I haven't read over them:
-           * http://www.onlamp.com/pub/a/python/2000/09/27/numerically.html
-           * http://www.scipy.org/EricsBroadcastingDoc
+    Broadcasting
+        TRANSFERRED
         
     Build
         see :term:`Compilation`
@@ -50,14 +152,7 @@ Glossary of terminology
         The :term:`mode` defines how optimizations and stabilizations will be introduced, and defines which linker will be used.
 
     Constant
-        See :term:`Value`        
-        
-        Constant (`Constant API
-        <http://lgcm.iro.umontreal.ca/epydoc/theano.gof.graph.Constant-class.html
-        doc>`_) also has an additional property: it is forbidden for an
-        :term:`Op` to modify the state of the data it contains. This
-        makes it eligible to participate in numerous optimizations:
-        constant inlining in C code, constant folding, etc.
+        TRANSFERRED    
 
     DType
         the numeric type for :term:`Tensor` elements
@@ -425,3 +520,4 @@ Glossary of terminology
         Theano computation). This can be practical because the compiler
         knows how to assign values to those nodes, thereby creating a
         sort of closure.
+..

doc/index.txt

 
+.. _theano:
+
 ======
 Theano
 ======
@@ -41,18 +43,18 @@ Getting started
 TODO: I want to bold the links below. How the fuck do I bold links? ``**`link name`_**`` doesn't work! :(
 
 
-`Installing Theano`_
+:ref:`install`
   Instructions to download and install Theano on your system.
 
 
-`Basic tutorial`_
+:ref:`basictutorial`
   Getting started with Theano's basic features. Go there if you are new!
 
 
-`Advanced tutorial`_
+:ref:`advtutorial`
   This tutorial is for more advanced users who want to define their own
   operations and optimizations. It is recommended to go through the
-  `Basic tutorial`_ first.
+  :ref:`basictutorial` first.
 
 
 
@@ -60,9 +62,14 @@ Contents
 ========
 
 .. toctree::
-   :glob:
+   :maxdepth: 2
 
-   *
+   install
+   tutorial/index
+   advtutorial/index
+   advanced/index
+   indexes/index
+   LICENSE
 
 
 Contact us
@@ -88,10 +95,6 @@ theano-dev_ mailing list.
 .. _numpy: http://numpy.scipy.org/
 .. _BLAS: http://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms
 
-.. _Installing Theano: install.html
-.. _Basic tutorial: tutorial/index.html
-.. _Advanced tutorial: advtutorial/index.html
-
 .. _theano-users: http://groups.google.com/group/theano-users?pli=1
 .. _theano-dev: http://groups.google.com/group/theano-dev?pli=1
 .. _task list: http://lgcm.iro.umontreal.ca/theano/query?status=accepted&status=assigned&status=new&status=reopened&group=milestone&max=200&col=id&col=summary&col=status&col=owner&col=type&col=priority&col=component&col=time&report=9&order=priority

scripts/docgen.py

@@ -75,12 +75,12 @@ if __name__ == '__main__':
 
     import gen_oplist
     print 'Generating oplist...'
-    gen_oplist.print_file(open('%s/doc/doc/oplist.txt' % throot, 'w'))
+    gen_oplist.print_file(open('%s/doc/indexes/oplist.txt' % throot, 'w'))
     print 'oplist done!'
 
     import gen_typelist
     print 'Generating typelist...'
-    gen_typelist.print_file(open('%s/doc/doc/typelist.txt' % throot, 'w'))
+    gen_typelist.print_file(open('%s/doc/indexes/typelist.txt' % throot, 'w'))
     print 'typelist done!'
 
     def mkdir(path):

scripts/gen_oplist.py

@@ -7,6 +7,7 @@ sys.path[0:0] = [theano_path]
 from theano import gof
 
 def print_title(file, title_string, under_char, over_char=''):
+
     l = len(title_string)
     if over_char:
         print >>file, over_char * l
@@ -157,6 +158,8 @@ def print_entries(file, ops, constructors):
 
 def print_file(file):
 
+    print >>file, '.. _oplist:\n\n'
+
     print_title(file, "Op List", "~", "~")
     print >>file, """
 This page lists the `Op Classes` and `constructors` that are provided by the Theano library.

scripts/gen_typelist.py

@@ -4,6 +4,8 @@ from gen_oplist import print_title, print_hline
 
 def print_file(file):
 
+    print >>file, '.. _typelist:\n\n'
+
     print_title(file, "Type List", "~", "~")
 
     print >>file, "*THIS PAGE IS A PLACEHOLDER: WRITEME*"