Added more documentation from wiki

doc/doc/glossary.txt

@@ -21,6 +21,8 @@ Glossary of terminology
         
         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.
+
+        See :ref:`intro_to_ops`.
         
     Broadcasting
         implicit tensor repmat
@@ -83,6 +85,8 @@ Glossary of terminology
     Function
         callable object representing a compiled graph
 
+        It is created through ``theano.function``.
+
         WRITEME
 
     Graph
@@ -233,6 +237,8 @@ Glossary of terminology
             * performing the calculation of outputs from given inputs (via the ``perform``),
             * producing c code to perform calculation of outputs from inputs (via ``c_code, c_code_cleanup, c_support_code, c_headers, c_libraries, c_compile_args``)
             * [optionally] building gradient-calculating graphs (via ``grad``).
+
+        See :ref:`intro_to_ops`.
         
     Optimization
         graph transformation for faster execution
@@ -267,6 +273,8 @@ Glossary of terminology
                 a Result with a data field.
             :term:`Constant`
                 like ``Value``, but the data it contains cannot be modified.
+
+        See :ref:`intro_to_types`.
         
         Code Example:
         
@@ -412,6 +420,8 @@ Glossary of terminology
         see :ref:`CodeGeneration` for a more general intro to how C code is generated.
 
         See also :term:`Theano type instance (TTI) <TTI>`.
+
+        See :ref:`intro_to_types`.
         
 
     Value

doc/doc/graph.txt

+.. _graph:
+
 ================================================
 Graph: interconnected Apply and Result instances
 ================================================
 
+*TODO: There is similar documentation in the* `wiki <http://lgcm.iro.umontreal.ca/theano/wiki/GraphStructures>`__. *However, the
+wiki has more information about certain topics. Merge these two pieces of
+documentation.*
+
 In theano, a graph is an implicit concept, not a class or an instance.
 When we create `Results` and then `apply` `operations` to them to make more `Results`, we build a bi-partite, directed, acyclic graph.
 Results point to `Apply` instances (via their `owner` attribute) and `Apply` instances point to `Results` (via their `inputs` and `outputs` fields).

doc/doc/internal.txt

-.. _extending:
+.. _internal:
 
 ================
 Internal notes

doc/doc/intro_to_ops.txt

+.. _intro_to_ops:
+
+===================
+Introduction to Ops
+===================
+
+This page introduces :term:`Apply` and :term:`Op`.  To start, let's consider the following program:
+
+.. code-block:: python
+
+    import theano
+    from theano import tensor
+
+    a = tensor.constant(1.5)
+    b = tensor.fscalar()    
+    c = a + b                       # Apply the Add Op to results a and b.
+    d = c + c                       # Apply the Add Op to the result c in two ways
+    f = theano.function([b], [d])   # Convert Op applications to callable objects.
+    assert 8.0 == f(2.5)            # Bind 2.5 to 'b' and evaluate 'd' by running
+                                    #   Add.perform() twice.
+
+The python variables ``a,b,c,d`` all refer to classes of type :term:`Result` (introduced in :ref:`intro_to_types`), whereas :term:`Apply` and :term:`Op` classes serve to connect them together.
+:term:`Apply` instances permit ``theano.function`` to figure out how to compute outputs from inputs (in this case, ``d`` from ``b``).  Comparing with python's normal types, 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.
+
+There are three fields which are fundamental to an ''':term:`Apply`''' instance:
+  * ``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 which function is being applied here. 
+
+Now that we've seen :term:`Result` and :term:`Apply` we can begin to understand what ``theano.function`` does.  
+When a :term:`Result` is the output of an :term:`Apply`, it stores a reference to this ``owner``).
+Similarly, each :term:`Apply` stores a list of its inputs.
+In this way, :term:`Result` and :term:`Apply` instances together form a bi-partite directed acyclic graph: :term:`Results <Result>` point to :term:`Applies <Apply>` via the ``.owner`` attribute and :term:`Applies <Apply>` to :term:`Results <Result>` via the ``.inputs`` attribute.
+When we call ``theano.function`` one of the first things that happens is a search through this graph from the :term:`Results <Result>` given as the function's outputs; this search establishes how to compute the outputs from inputs, and finds all the constants and values which contribute to the outputs.
+
+:term:`Op` instances, like :term:`Type` instances, tell ``theano.function`` what to do with the nodes it finds in this graph search.
+An :term:`Op` instance has a ``perform`` method which implements the computation that transforms the data associated with ``Apply.inputs`` to the data associated with ``Apply.outputs``.
+
+What's Next?
+============
+
+ * Read more about theano's :ref:`Graph`.
+ * Learn :ref:`HowtoMakeOps`.
+

doc/doc/intro_to_types.txt

+.. _intro_to_types:
+
+=====================
+Introduction to Types
+=====================
+
+This page introduces ``theano.Result`` and ``theano.Type``.  
+
+
+class ``Result``
+------------------
+
+Consider the following program:
+
+
+.. code-block:: python
+
+    import theano
+    from theano import tensor
+    
+    a = tensor.constant(1.5)        # declare a symbolic constant
+    b = tensor.fscalar()            # declare a symbolic floating-point scalar
+    
+    c = a + b                       # create a simple expression
+    
+    f = theano.function([b], [c])   # convert the expression into a callable function
+    
+    assert 4.0 == f(2.5)            # bind 2.5 to 'b' and evaluate 'c'
+
+The python variables ``a,b,c`` all refer to classes of type ``theano.Result``.
+A ``Result`` is theano's version of a variable.  There are three important kinds of ``Results``: 
+
+ * ones that are the result of an expression (such as c) are the normal ``Result``
+ * constants, which are of subclass ``Constant``
+ * closures, which are of subclass ``Value``.
+
+In our example, ``a`` refers to a ``Constant`` and ``b`` is a normal
+``Result``.  Although ``b`` is not the result of an expression in our
+graph, it is necessary that ``b`` be the result of an expression outside
+the graph; that's why ``b`` must be listed as one of the inputs of our
+compiled function ``f``.  We could have named ``a`` as an input to our
+function too (even though it is declared as a constant) but as the example
+shows, we don't have to because it already has a value associated with it.
+
+The other kind of ``Result`` is the ``Value`` which implements
+closures.  It comes into play in the following variation on the program
+above.
+
+.. code-block:: python
+
+	import theano
+	from theano import tensor
+	
+	a = tensor.value(1.5)           # declare a symbolic value
+	b = tensor.fscalar()            # declare a symbolic floating-point scalar
+	
+	c = a                           # create a second name for a
+	c += b                          # c refers to the result of incrementing a by b
+	
+	f = theano.function([b], [c])   # convert the expression into a callable function
+	
+	assert 4.0 == f(2.5)            # bind 2.5 to 'b' and evaluate 'c' (increments f's copy of a)
+	assert 6.5 == f(2.5)            # bind 2.5 to 'b' and evaluate 'c' (increments f's copy of a)
+	
+	g = theano.function([b], [c])   # make another function like f
+	assert 4.0 == g(2.5)            # g got a fresh version of the closure, not the one modified by f
+
+A ``Value`` is a ``Result`` that is not computed by any expression,
+but need not be an input to our function because it already has a value.
+In this example, ``a`` is a ``Value`` instance. [''Too many negations
+in the previous sentence for me to figure out what it means.''] One of
+the expressions that use it in a given function can modify it and the
+modified value will persist between evaluations of that function.  If two
+expressions try to modify the same ``Value`` then ``theano.function``
+will raise an exception.  Incidentally, ``theano.function`` might choose
+to work in-place on internal results at its discretion... once you tell
+it which input and output results you care about, then it basically
+has free reign over all the others. [''Shouldn't this sentence be a
+new paragraph?'']
+
+class ``Type``
+----------------
+
+[http://lgcm.iro.umontreal.ca:8000/theano/chrome/common/epydoc/theano.gof.type.Type-class.html autodoc of theano.Type]
+
+A ``Type`` instance hides behind each ``Result`` and indicates what
+sort of value we can associate with that ``Result``.  Many ``Result``
+instances can use the same ``Type`` instance.  In our example above
+``theano.fscalar`` is a ``Type`` instance, and calling it generated
+a ``Result`` of that type.   The ``Type`` of a ``Result`` is a
+contract to expression implementations; [''previous phrase is really
+convoluted. Just use standard terminology from programming language
+specification. It's like a type declaration, right?''] it's a promise
+that at computation time, the actual value (not symbolic anymore)
+will have a certain interface... to really go into detail is beyond the
+scope of this user intro, but for example if a ``Result`` has a type
+``tensor.fvector`` then we'll compute a 1-dimensional numpy.ndarray of
+dtype('float64') for it[[''How to get float32?'']].  ``Type`` instances
+are also responsible for exposing actual data to C code, and packaging it
+back up for python when ``theano.function`` is asked to generate C code.
+To learn more about that, read the introduction to CodeGeneration.
+
+What's Next?
+--------------
+
+The companion to Result and Type is :ref:`intro_to_ops`, which develops a similar story for the expression objects themselves.
+