merge

doc/install.txt

@@ -68,36 +68,50 @@ Manual install
 --------------
 
 There are two ways to get the source: through mercurial (required for
-library developers) or through a unix compressed archive.  There are
+library developers) or through a Unix compressed archive.  There are
 no stable releases yet.
 
 *To get the source via mercurial,* you must have `mercurial <http://www.selenic.com/mercurial/wiki/>`__ installed.
 
-Get the source and run the tests like this:
+You can get the source like this:
 
 .. code-block:: bash
 
     hg clone http://pylearn.org/hg/theano Theano
-    ln -s Theano/theano <someplace on your PYTHONPATH>/theano
-    cd Theano
-    nosetests #execute all the tests
 
-All tests should pass. If some test fails on your machine, you are
-encouraged to tell us what went wrong on the theano-users mailing
-list.
+The subdirectory Theano/theano has to be in your PYTHONPATH. In order to do
+that, you can either create a symbolic link to Theano/theano in a directory
+already mentionned in your PYTHONPATH environment variable, or modify the
+PYTHONPATH so that it mentions Theano.
 
-The environment variable PYTHONPATH should be modified to tell Python
-where to find Theano. In bash, you may do this:
+To create a symbolic link:
 
 .. code-block:: bash
 
-    export PYTHONPATH=<path to Theano/theano>:$PYTHONPATH
+    ln -s Theano/theano <someplace on your PYTHONPATH>/theano
+
+To modify the environment variable PYTHONPATH in bash, you may do this:
+
+.. code-block:: bash
+
+    export PYTHONPATH=<path to Theano's parent dir>/Theano:$PYTHONPATH
 
 In csh:
 
 .. code-block:: csh
 
-    setenv PYTHONPATH <path to Theano/theano>:$PYTHONPATH 
+    setenv PYTHONPATH <path to Theano's parent dir>/Theano:$PYTHONPATH
+
+Once you have completed these steps, you should run the tests like this:
+
+.. code-block:: bash
+
+    cd Theano
+    nosetests #execute all the tests
+
+All tests should pass. If some test fails on your machine, you are
+encouraged to tell us what went wrong on the :ref:`theano-users` mailing
+list.
 
 To update your library to the latest revision, change directory (`cd`)
 to your `Theano` folder and execute the following command:
@@ -118,25 +132,32 @@ Two environment variables are used to control automatic code
 generation. It is possible to use theano in a way which avoids all
 automatic code generation, but that way is much, much slower.
 
-- `THEANO_BLAS_LDFLAGS`: 
-    a space-separated list of library names to link against for BLAS functions. Default: `-lblas`
+- `THEANO_BLAS_LDFLAGS`:
+    A space-separated list of options (flags) that will be passed to the
+    compiler. It should include library names to link against for BLAS
+    functions. Default: `-lblas`.
 
 - `THEANO_COMPILEDIR`:
-    a directory with read/write access permissions where theano will store
-    autogenerated code and c modules. Default: `$HOME/.theano`. If this
+    A directory with read/write access permissions where theano will store
+    autogenerated code and C modules. Default: `$HOME/.theano`. If this
     directory does not exist or does not have the correct permissions,
     theano will try to create it with the correct permissions. If that fails,
     an exception will be raised and no C code will be compiled.
 
-- `THEANO_DEFAULT_MODE`: 
-    string value specifying the default mode to use when compiling theano
-    graphs. This can be one of the strings defined in theano.compile.mode
-    Possible values so far are: FAST_COMPILE, FAST_RUN and DEBUG_MODE.
+- `THEANO_DEFAULT_MODE`:
+    String value specifying the default mode to use when compiling theano
+    graphs. This can be one of the strings defined in
+    :api:`theano.compile.mode`.
+    Possible values so far are:
+    - FAST_COMPILE,
+    - FAST_RUN and
+    - DEBUG_MODE.
     Omitting this variable defaults the mode to FAST_RUN.
 
-- `THEANO_UNITTEST_SEED`: 
-    an integer value specifying which seed should be used when running unit tests.
-    Setting this value will make the unit tests deterministic. 
+- `THEANO_UNITTEST_SEED`:
+    An integer value specifying which seed should be used when
+    running unit tests.
+    Setting this value will make the unit tests deterministic.
 
 ---
 Mac
@@ -144,7 +165,11 @@ Mac
 
 - Install `MacPorts <http://www.macports.org/>`__.
 
-- `sudo port install gcc42 py25-zlib py25-numpy py25-scipy mercurial`.
+-
+    .. code-block:: bash
+
+        $ sudo port install gcc42 py25-zlib py25-numpy py25-scipy mercurial
+
     Note that compiling gcc42 takes a significant time (hours) so it's probably
     not the best solution if you're in a rush! In my (Doomie) experience, scipy
     failed to compile the first time I tried the command, but the second time
@@ -153,7 +178,7 @@ Mac
 - Install some kind of BLAS library (TODO: how?)
 
 - Set THEANO_BLAS_LDFLAGS to something which will link against said BLAS
-  library.  (e.g., `THEANO_BLAS_LDFLAGS='-lcblas -latlas -lgfortran'`).
+  library.  E.g., `THEANO_BLAS_LDFLAGS='-lcblas -latlas -lgfortran'`.
 
 TODO: check if this is still valid
 
@@ -179,6 +204,7 @@ This should give you the gist of it:
    Usage: doc/scripts/docgen.py [OPTIONS]
      -o <dir>: output the html files in the specified dir
      --rst: only compile the doc (requires sphinx)
+     --nopdf: do not produce a PDF file from the doc, only HTML
      --epydoc: only compile the api documentation (requires epydoc)
      --help: this help
 

doc/scripts/docgen.py

@@ -68,6 +68,7 @@ if __name__ == '__main__':
         print 'Usage: %s [OPTIONS]' % sys.argv[0]
         print '  -o <dir>: output the html files in the specified dir'
         print '  --rst: only compile the doc (requires sphinx)'
+        print '  --nopdf: do not produce a PDF file from the doc, only HTML'
         print '  --epydoc: only compile the api documentation (requires epydoc)'
         print '  --help: this help'
         sys.exit(0)