Polish up documentation

doc/advanced/index.txt

@@ -5,21 +5,20 @@
 Advanced Topics
 ===============
 
-Structure
-=========
-
 .. toctree::
-   :maxdepth: 2
+    :maxdepth: 2
    
-   debug_faq
-   debugmode
-   env
-   features
-   optimization
-   compilation
-   ccodegen
-   function
-   module
-   pipeline
-   profilemode
-   unittest
+    pipeline
+    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
 
-  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)
+      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.