Polish up documentation

doc/advanced/index.txt

@@ -5,21 +5,20 @@
 Advanced Topics
 ===============
 
-Structure
-=========
-
 .. toctree::
     :maxdepth: 2
    
-   debug_faq
-   debugmode
-   env
-   features
-   optimization
-   compilation
-   ccodegen
-   function
-   module
     pipeline
-   profilemode
     unittest
+    profilemode
+    debug_faq
+    debugmode
+
+
+.. env
+.. features
+.. optimization
+.. compilation
+.. ccodegen
+.. function
+.. module

doc/advanced/pipeline.txt

@@ -10,7 +10,7 @@ compiling a Theano function.
 
 
 Definition of the computation graph
-===================================
+-----------------------------------
 
 By creating Theano :ref:`Variables <variable>` using
 ``theano.tensor.lscalar`` or ``theano.tensor.dmatrix`` or by using
@@ -22,9 +22,9 @@ in the :ref:`graphstructures` article.
 
 
 Compilation of the computation graph
-====================================
+------------------------------------
 
-Once the user has built a computation graph, he can use
+Once the user has built a computation graph, she can use
 ``theano.function`` or a ``theano.Method`` in a ``theano.module`` in
 order to make one or more functions that operate on real data. Both
 function and Method take a list of input :ref:`Variables <variable>`
@@ -37,7 +37,7 @@ computation graph in the compilation phase:
 
 
 Step 1 - Create an Env
-======================
+^^^^^^^^^^^^^^^^^^^^^^
 
 The subgraph given by the end user is wrapped in a structure called
 :ref:`env`. That structure defines several hooks on adding and
@@ -56,7 +56,7 @@ inputs declared as immutable.
 
 
 Step 2 - Execute main Optimizer
-===============================
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Once the Env is made, an :ref:`optimizer <optimization>` is produced
 by the :ref:`mode` passed to ``function`` or to the Method/Module's
@@ -68,7 +68,7 @@ The optimizer is typically obtained through :ref:`optdb <optdb>`.
 
 
 Step 3 - Execute linker to obtain a thunk
-=========================================
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Once the computation graph is optimized, the :ref:`linker` is
 extracted from the Mode. It is then called with the Env as argument to
@@ -99,21 +99,10 @@ case if ``borrow`` was True, the thunk would be allowed to reuse (or
 
 
 Step 4 - Wrap the thunk in a pretty package
-===========================================
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The thunk returned by the linker along with input and output
 containers is unwieldy. ``function`` and ``Method`` hide that
 complexity away so that it can be used like a normal function with
 arguments and return values.
 
-
-
-
-
-
-
-
-
-
-
-

doc/advanced/profilemode.txt

@@ -10,7 +10,7 @@ an argument when compiling your graph. Using ProfileMode is a three-step
 process.
 
 Creating a ProfileMode Instance
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------
 
 First create a ProfileMode instance. 
 
@@ -33,7 +33,7 @@ find where most of the computation time is being spent. In this context,
 'fast_run' optimizer and ``gof.OpWiseCLinker`` are the most appropriate choices.
 
 Compiling your Graph with ProfileMode
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Once the ProfileMode instance is created, simply compile your graph as you
 would normally, by specifying the mode parameter.
@@ -45,7 +45,7 @@ would normally, by specifying the mode parameter.
 >>> minst = m.make(mode=profmode)
 
 Retrieving Timing Information
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Once your graph is compiled, simply run the program or operation you wish to
 profile, then call ``profmode.print_summary()``. This will provide you with

doc/advanced/unittest.txt

@@ -15,7 +15,7 @@ Unit Testing revolves around the following principles:
 This page is in no way meant to replace tutorials on Python's unittest module, for this we refer the reader to the `official documentation <http://docs.python.org/library/unittest.html>`_.  We will however adress certain specificities about how unittests relate to theano.
 
 How to Run Unit Tests ?
-=======================
+-----------------------
 
 Running all unit tests
 
@@ -36,7 +36,7 @@ Running a specific unit test
 
 
 Folder Layout
-=============
+-------------
 
 "tests" directories are scattered throughout theano. Each tests subfolder is
 meant to contain the unittests which validate the .py files in the parent folder.

doc/conf.py

@@ -42,8 +42,8 @@ source_suffix = '.txt'
 master_doc = 'contents'
 
 # General substitutions.
-project = 'theano'
-copyright = '2008-2009, LISA lab'
+project = 'Theano'
+copyright = '2008--2009, LISA lab'
 
 # The default replacements for |version| and |release|, also used in various
 # other places throughout the built documents.
@@ -64,7 +64,7 @@ today_fmt = '%B %d, %Y'
 
 # List of directories, relative to source directories, that shouldn't be searched
 # for source files.
-#exclude_dirs = []
+exclude_dirs = ['images']
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None
@@ -101,7 +101,7 @@ html_style = 'default.css'
 
 # The name of an image file (within the static path) to place at the top of
 # the sidebar.
-#html_logo = None
+html_logo = 'images/theano_logo-200x67.png'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -111,7 +111,7 @@ html_style = 'default.css'
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['.static']
+html_static_path = ['.static', 'images']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
@@ -119,7 +119,7 @@ html_last_updated_fmt = '%b %d, %Y'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
-#html_use_smartypants = True
+html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
 #html_sidebars = {}
@@ -159,18 +159,19 @@ htmlhelp_basename = 'theanodoc'
 #latex_paper_size = 'letter'
 
 # The font size ('10pt', '11pt' or '12pt').
-#latex_font_size = '10pt'
+latex_font_size = '11pt'
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, document class [howto/manual]).
 latex_documents = [
   ('contents', 'theano.tex', 'theano Documentation',
-   'LISA lab', 'manual'),
+   'LISA lab, University of Montreal', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
-#latex_logo = None
+#latex_logo = 'images/snake_theta2-trans.png'
+latex_logo = None
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.

doc/contents.txt

@@ -6,7 +6,7 @@ Contents
 ========
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
 
    LICENSE
    introduction
@@ -16,7 +16,9 @@ Contents
    advanced_tutorial/index
    advanced/index
    indexes/index
-   examples/index
    glossary
    links
    internal/index
+
+
+..   examples/index

doc/install.txt

 
 .. _install:
 
-=================
+
 Installing Theano
 =================
 
@@ -9,7 +9,7 @@ Installing Theano
     If you are a member of LISA Labo, have a look at :ref:`lisa_labo` for
     lab-specific installation instructions.
 
-------------
+
 Requirements
 ------------
 
@@ -43,7 +43,6 @@ The following libraries and software are optional:
         To download bleeding-edge 
 
 
-------------
 Easy install
 ------------
 
@@ -63,7 +62,6 @@ on your system:
 .. Theano, when we figure out where to put it.
 
 
---------------
 Manual install
 --------------
 
@@ -124,7 +122,6 @@ You may also download the latest source directly as a gzip'd tar file:
 `<http://pylearn.org/hg/theano/archive/tip.tar.gz>`__.
 
 
----------------------------
 Configuring the environment
 ---------------------------
 
@@ -161,7 +158,7 @@ automatic code generation, but that way is much, much slower.
     running unit tests.
     Setting this value will make the unit tests deterministic.
 
----
+
 Mac
 ---
 
@@ -185,7 +182,7 @@ Mac
 TODO: check if this is still valid
 
 
--------
+
 Windows
 -------
 
@@ -194,7 +191,6 @@ never even been tested, so feel free to explore this uncharted
 territory and inform us of your progress!
 
 
-----------------------------
 Generating the documentation
 ----------------------------
 

doc/internal/index.txt

@@ -8,14 +8,12 @@ Internal documentation
 If you're feeling ambitious, go fix some `pylint
 <http://lgcm.iro.umontreal.ca/auto_theano_pylint/pylint_global.html>` errors!
 
-Structure
-=========
-
 .. toctree::
    :maxdepth: 2
 
    dev_start_guide
-   python
-   hg_primer
+   lisa_labo
    mammouth
    metadocumentation
+   python
+   hg_primer

doc/internal/mammouth.txt

@@ -4,13 +4,17 @@ Running Theano on Mammouth
 
 To run Theano on the Mammouth cluster, follow these simple steps:
 
-* Make sure to source Fred's .local.bashrc file. It contains all the goodies for using the latest and greatest (optimized) libraries (numpy, scipy, etc.)
->>> source /home/bastienf/.local.bashrc
+    * Make sure to source Fred's .local.bashrc file. It contains all
+      the goodies for using the latest and greatest (optimized) libraries
+      (numpy, scipy, etc.)
 
-* set THEANO_BLAS_LDFLAGS='-lmkl -lguide -fopenmp'
+      >>> source /home/bastienf/.local.bashrc
+
+      Perhaps even put this in your ``.bashrc``
+
+    * ``set THEANO_BLAS_LDFLAGS='-lmkl -lguide -fopenmp'``
 
       Note: the -lguide flag works, however the fix should probably be considered temporary.
       Intel has deprecated libguide.so in favor of the newer library libiomp5.so. However, 
       both libraries are mutually exclusive and one component (theano, numpy or scipy?) already
       seems to be using libguide.so (hence -liomp5 causes a linking error when compiling thunks)
-

doc/internal/metadocumentation.txt

@@ -90,6 +90,7 @@ When you push to the main repository, the following file is run::
 It calls ``epydoc`` and ``sphinx`` on the code.
 
 *It would be nice to explain this stuff in a little more depth:*
+
  * Who calls refresh-epydoc.sh ?
  * What exactly does it do?
  * Where does the output go?
@@ -145,6 +146,7 @@ TO WRITE
 ---------------------------------------
 
 *There is other stuff to document here, e.g.:*
+
  * where the documentation is getting built, and epy.
  * How epydoc and sphinx are integrated
  * Explain the special magic in ./doc/scripts/docgen.py

doc/introduction.txt

@@ -10,13 +10,6 @@ efficiently evaluate mathematical expressions involving multi-dimensional
 arrays. Using Theano, it is not uncommon to see speed improvements of
 ten-fold over using pure NumPy.
 
-The term "mathematical expressions" is used broadly to mean a
-computation with some inputs, possibly which might update the inputs
-in-place. Neural net forward propagation is an expression, as is fprop +
-bprop + a weight-update implementing stochastic gradient descent. Feature
-extraction from audio of zero-crossing, 16 mfcc, and 128 rceps coefficients is
-also an expression.
-
 Theano melds some aspects of a computer algebra system (CAS) with
 aspects of an optimizing compiler. It can even transform some or
 all of the mathematical expression into C code and compile it into

doc/links.txt

 
 .. _links:
 
-=====
+
 Links
 =====
 
@@ -9,7 +9,7 @@ This page lists links to various resources.
 
 
 Theano requirements
-===================
+-------------------
 
 - mercurial_: A distributed revision control system (RCS).
 - nosetests_: A system for unit tests.
@@ -19,7 +19,7 @@ Theano requirements
 
 
 Libraries we might want to look at or use
-=========================================
+-----------------------------------------
 
 This is a sort of memo for developers and would-be developers.
 

doc/numpy.txt

@@ -2,9 +2,9 @@
 .. _numpy:
 
 
-===============
+***************
 NumPy refresher
-===============
+***************
 
 Here are some quick guides to NumPy:
   * `Numpy quick guide for Matlab users <http://www.scipy.org/NumPy_for_Matlab_Users>`__
@@ -15,10 +15,9 @@ Here are some quick guides to NumPy:
     .. [TODO: More doc, e.g. see _test_tensor.py]
 
 
-
----------------------------------------
 Matrix conventions for machine learning
----------------------------------------
+=======================================
+
 
 Rows are horizontal and columns are vertical.
 Every row is an example. Therefore, inputs[10,5] is a matrix of 10 examples with 5 dimensions per.