Moving documentation from trac to sphinx

doc/README.txt

@@ -8,7 +8,7 @@ README: theano
 Project Description
 ===================
 
-Theano is a python library for manipulating and evaluating expressions, especially matrix-valued ones.
+Theano is a python library and optimizing compiler for manipulating and evaluating expressions, especially matrix-valued ones.
 What does Theano do that Python and numpy do not?
 
 - *execution speed optimizations*: Theano can use `g++` to compile parts your expression graph into native machine code, which runs much faster than python.
@@ -37,13 +37,17 @@ Here's a very simple example of how to use Theano.  It doesn't show off many of
 
 Theano is not a programming language in the normal sense because you write a program in Python that builds expressions for Theano.  Still it is like a programming language in the sense that to use theano, you have to 
 
-- declare variables ({{{a,b}}}) and give their types
+- declare variables (``a,b``) and give their types
 
 - build expressions for how to put those variables together
 
 - compile expression graphs to functions in order to use them for computation.
 
-It is good to think of `theano.function` as the interface to a compiler which builds a callable object from a purely symbolic graph.
+It is good to think of ``theano.function`` as the interface to a compiler
+which builds a callable object from a purely symbolic graph; one of
+theano's most important features is that ``theano.function`` can
+optimize a graph, and even compile some or all of it into native machine
+instructions if you pass ``linker='c'`` as a keyword argument.
 
 
 License
@@ -55,9 +59,6 @@ Theano is licensed under a BSD-like license.  See the LICENSE file in the projec
 Installation
 ============
 
-(See also the :wiki:`InstallationNotes` on the wiki.)
-
-
 Software Requirements
 ---------------------
 
@@ -94,15 +95,24 @@ Get the source and run the tests like this:
     cd Theano
     nosetests #execute all the tests
 
-All tests should pass. From time to time, their is some test that are know to fail, but normally we know them and are trying to fix them. But to be sure contact us about them. 
+All tests should pass. From time to time, there is some test that are
+know to fail, but normally we know them and are trying to fix them. But
+to be sure contact us about them.
 
-To define PYTHONPATH if it don't exist:
+The environment variables PYTHONPATH should be modified to allow python
+import. In bash do this: 
 
 .. code-block:: bash
-export PYTHONPATH=<path to theano>:$PYTHONPATH
 
+    export PYTHONPATH=<path to theano>:$PYTHONPATH
+
+In csh:
+
+.. code-block:: csh
+
+    setevn PYTHONPATH <path to theano>:$PYTHONPATH 
 
-To update your library to the latest on pylearn.org, change directory (`cd`) to this `theano` folder and type
+To update your library to the latest on pylearn.org, change directory (`cd`) to this `Theano` folder and type
 
 .. code-block:: bash
 
@@ -112,7 +122,7 @@ To update your library to the latest on pylearn.org, change directory (`cd`) to
 `<http://pylearn.org/hg/theano/archive/tip.tar.gz>`__.
 
 Configuring the environment
-------------------
+---------------------------
 
 Two environment variables are used to control automatic code generation.
 (It is possible to use theano in a way that avoids all automatic code generation, but the functions you make using {{{theano.function}}} will execute more slowly.)
@@ -184,6 +194,14 @@ Use something like the following in your .bashrc:
     # Theano is not process-safe or thread-safe in this sense.
     THEANO_COMPILEDIR=/ltmp/<username>_theano
 
+You may also need to run the following from your shell: 
+
+.. code-block:: bash
+
+    module add python      # for the current shell session 
+    module initadd python  # for this and future sessions 
+
+Lastly,  if ``./filename.py`` doesn't work, try ``python filename.py``.
 
 Running the Test Suite
 ======================

doc/doc/n00b.txt

@@ -44,14 +44,16 @@ In the following example, we will build a function `f(x) = x + 1.5`. We will the
     f = theano.function([x], [y])
 
     # We now bind 2.5 to an internal copy of x and evaluate an internal y,
-    # which we return.
-    # We assert that 4.0 == f(2.5) = 2.5 + 1.5
-    assert 4.0 == f(2.5)
+    # which we return (actually f(2.5) returns a list because theano 
+    # functions in general can return many things). 
+    # We assert that 4.0 == f(2.5)[0] = 2.5 + 1.5 
+    assert 4.0 == f(2.5)[0] 
 
-In the example above, `c`, `x`, and `y` are each a ''symbolic'' result_. They
-are symbolic because they stand for variables and have a type_, but
-do not necessarily store actual values.  Not yet, at least.  (To give them
-values, we will have to `evaluate` them.  More on this below.)
+In the example above, `c`, `x`, and `y` are each a ''symbolic''
+result_. They are symbolic because they stand for variables and have
+a type_, but do not actually store instantiated variables.  Not yet,
+at least.  (To give them values, we will have to `evaluate` them.
+More on this below.)
 
 .. _result: glossary.html#result
 .. _type: glossary.html#type
@@ -60,14 +62,15 @@ Since we are using the addition operator (`x + c`) here on symbolic results, the
 output `y` is also symbolic.  The `+` corresponds to an ''operation'' in theano
 terminology, or ''op'' for short.
 
-We use these results and ops to construct a `symbolic graph`_.  The graph is
-symbolic because we declare what it computes, but do not actually perform any
-computation.  Some type-checking is done on while we build our graphs, so if you
-try to do something really crazy you'll see an exception right away.
+We use these results and ops to construct a `symbolic graph`_. The graph
+is symbolic because we declare what it computes, but do not actually
+perform any computation.  Some type-checking is done on while we build
+our graphs, so if you try to do something really crazy you'll see an
+exception right away.
 
 .. _symbolic graph: glossary.html#symbolicgraph
 
-To actually use our graph for computation, we have to compile (or build) it into
+To actually use our graph for computation, we have to compile_ (or build_) it into
 a function `f`.   The compiled function is actually capable of performing
 computation.  So after we have built f, we use it to compute the value of y from
 a `value input` x.  Some argument checking is only possible at run-time, so if

doc/index.txt

@@ -13,10 +13,11 @@ Theano
 A python library for manipulating and evaluating matrix expressions
 -------------------------------------------------------------------
 
-Theano is a library in Python, built to evaluate complicated
-expressions (especially matrix-valued ones) as quickly as possible.
-It was written at LISA_ to explore techniques for machine learning.
-Our project uses the name to honour the ancient Greek mathematician. 
+Theano is a library and optimizing compiler in Python, built to
+evaluate complicated expressions (especially matrix-valued ones) as
+quickly as possible.  It was written at LISA_ to explore techniques
+for machine learning.  Our project uses the name to honour the ancient
+Greek mathematician.
 
 --------------------------------------------------------------------------------