Split concepts and extending up

doc/doc/concepts.txt

+.. _concepts:
+
+================
+Concepts
+================
+
+This page introduces some important terminology for describing how theano
+works.
+
+Lets start by looking at what happens in a simple theano program.
+
+.. code-block:: python
+
+    x = tensor.matrix('x')
+    y = tensor.matrix('y')
+    z = x + y
+    f = theano.function(input=[x,y], output=z, mode='FAST_RUN')
+    print f(numpy.ones(2,3), numpy.ones(2,3))
+
+The first three lines build a :term:`graph` whose nodes correspond to variables (``x,y,z``) and expressions (just the '+' here).
+The variables in such a graph are :term:`Result` instances of some
+:term:`Type`, and the expressions are :term:`Apply` instances of some
+:term:`Op`.
+
+The line ``f = theano.function([x,y], [z], mode='FAST_RUN')`` :term:`compiles
+<Compilation>`.
+the graph we built and returns a :term:`function` whose ``__call__`` method
+takes as arguments the values to use for ``x`` and ``y``.
+The :term:`mode` controls which :term:`transformations <Graph Transformation>` are applied to the graph as we compile it.
+
+The line ``print f(numpy.ones(2,3), numpy.ones(2,3))`` creates two
+matrices, and then uses f's ``__call__`` method to run the compiled
+function on those inputs.
+The compiled function is executed by a :term:`linker`, which was also specified by the :term:`mode` argument to ``function``.
+The instance f's ``__call__`` method returns a value for ``z`` (given ``x,y``) which we print.

doc/doc/extending.txt

+.. _extending:
+
 ================
 Extending theano
 ================
 
-This page introduces some important terminology for describing how theano
-works.  Below there is a list of HOWTO documents for extending theano.
-
-Lets start by looking at what happens in a simple theano program.
-
-.. code-block:: python
-
-    x = tensor.matrix('x')
-    y = tensor.matrix('y')
-    z = x + y
-    f = theano.function(input=[x,y], output=z, mode='FAST_RUN')
-    print f(numpy.ones(2,3), numpy.ones(2,3))
-
-The first three lines build a :term:`graph` whose nodes correspond to variables (``x,y,z``) and expressions (just the '+' here).
-The variables in such a graph are :term:`Result` instances of some
-:term:`Type`, and the expressions are :term:`Apply` instances of some
-:term:`Op`.
-
-The line ``f = theano.function([x,y], [z], mode='FAST_RUN')`` :term:`compiles
-<Compilation>`.
-the graph we built and returns a :term:`function` whose ``__call__`` method
-takes as arguments the values to use for ``x`` and ``y``.
-The :term:`mode` controls which :term:`transformations <Graph Transformation>` are applied to the graph as we compile it.
-
-The line ``print f(numpy.ones(2,3), numpy.ones(2,3))`` creates two
-matrices, and then uses f's ``__call__`` method to run the compiled
-function on those inputs.
-The compiled function is executed by a :term:`linker`, which was also specified by the :term:`mode` argument to ``function``.
-The instance f's ``__call__`` method returns a value for ``z`` (given ``x,y``) which we print.
-
-Theano was designed to be extensible to new :term:`types <Type>` of Result,
-new :term:`Ops <Op>` to use in symbolic computations,
-and new modes of compilation and execution.  When you're comfortable with the material above, move on to:
+When you're comfortable with the material in :ref:`concepts`, move on to:
 
 * HowtoCreateType create a new data type,
 * HowtoCreateOp create a new type of Op,

doc/doc/index.txt

@@ -13,7 +13,9 @@ developer documentation.
 - `Using Theano` covers how to *use* what is already in the Theano library to
   build graphs and evaluate them.
 
-- `Extending Theano` introduces how Theano works and explains how to add new
+- `Concepts` introduces how Theano works.
+
+- `Extending Theano` explains how to add new
   data and expression types, as well as optimizations to accompany them.
 
 - `Module`