# HG changeset patch
# User fsavard
# Date 1268926429 14400
# Node ID 9472d234db2eeabfbc8f67cefa041c520ab50dbf
# Parent  08b37147dec125e3068252bd17ef7cf1b7651c03
Added basics for documentation with sphinx and epydoc, by copying files from the Theano/doc directory

diff -r 08b37147dec1 -r 9472d234db2e doc/.build/PLACEHOLDER
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/.build/PLACEHOLDER	Thu Mar 18 11:33:49 2010 -0400
@@ -0,0 +1,1 @@
+sphinx doesn't like it when this repertory isn't available
diff -r 08b37147dec1 -r 9472d234db2e doc/.static/PLACEHOLDER
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/.static/PLACEHOLDER	Thu Mar 18 11:33:49 2010 -0400
@@ -0,0 +1,1 @@
+sphinx doesn't like it when this repertory isn't available
diff -r 08b37147dec1 -r 9472d234db2e doc/.templates/PLACEHOLDER
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/.templates/PLACEHOLDER	Thu Mar 18 11:33:49 2010 -0400
@@ -0,0 +1,1 @@
+sphinx doesn't like it when this repertory isn't available
diff -r 08b37147dec1 -r 9472d234db2e doc/.templates/layout.html
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/.templates/layout.html	Thu Mar 18 11:33:49 2010 -0400
@@ -0,0 +1,24 @@
+{% extends "!layout.html" %}
+
+{%- block extrahead %}
+{{ super() }}
+<script type="text/javascript">
+  var _gaq = _gaq || [];
+  _gaq.push(['_setAccount', 'UA-168290-9']);
+  _gaq.push(['_trackPageview']);
+</script>
+{% endblock %}
+
+{% block footer %}
+{{ super() }}
+<script type="text/javascript">
+  (function() {
+    var ga = document.createElement('script');
+    ga.src = ('https:' == document.location.protocol ?
+              'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+    ga.setAttribute('async', 'true');
+    document.documentElement.firstChild.appendChild(ga);
+  })();
+</script>
+{% endblock %}
+
diff -r 08b37147dec1 -r 9472d234db2e doc/LICENSE.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/LICENSE.txt	Thu Mar 18 11:33:49 2010 -0400
@@ -0,0 +1,30 @@
+.. _license:
+
+LICENSE
+=======
+
+Copyright (c) 2008--2009, Theano Development Team
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of Theano nor the names of its contributors may be
+      used to endorse or promote products derived from this software without
+      specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ''AS IS'' AND ANY
+EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff -r 08b37147dec1 -r 9472d234db2e doc/api/epydoc.conf
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/api/epydoc.conf	Thu Mar 18 11:33:49 2010 -0400
@@ -0,0 +1,152 @@
+# TODO:
+#   Get all graphs to work!
+
+
+[epydoc] # Epydoc section marker (required by ConfigParser)
+
+# The list of objects to document.  Objects can be named using
+# dotted names, module filenames, or package directory names.
+# Alases for this option include "objects" and "values".
+modules: pylearn
+
+# The type of output that should be generated.  Should be one
+# of: html, text, latex, dvi, ps, pdf.
+output: html
+
+# An integer indicating how verbose epydoc should be.  The default
+# value is 0; negative values will supress warnings and errors;
+# positive values will give more verbose output.
+verbosity: 1
+
+# A boolean value indicating that Epydoc should show a tracaback
+# in case of unexpected error. By default don't show tracebacks
+debug: 1
+
+# If True, don't try to use colors or cursor control when doing
+# textual output. The default False assumes a rich text prompt
+simple-term: 0
+
+
+### Generation options
+
+# The default markup language for docstrings, for modules that do
+# not define __docformat__.  Defaults to epytext.
+docformat: epytext
+
+# Whether or not parsing should be used to examine objects.
+parse: yes
+
+# Whether or not introspection should be used to examine objects.
+introspect: yes
+
+# Don't examine in any way the modules whose dotted name match this
+# regular expression pattern.
+#exclude
+
+# Don't perform introspection on the modules whose dotted name match this
+# regular expression pattern.
+#exclude-introspect
+
+# Don't perform parsing on the modules whose dotted name match this
+# regular expression pattern.
+#exclude-parse
+
+# The format for showing inheritance objects.
+# It should be one of: 'grouped', 'listed', 'included'.
+inheritance: grouped
+
+# Whether or not to inclue private variables.  (Even if included,
+# private variables will be hidden by default.)
+private: yes
+
+# Whether or not to list each module's imports.
+imports: yes
+
+# Whether or not to include syntax highlighted source code in
+# the output (HTML only).
+sourcecode: yes
+
+# Whether or not to includea a page with Epydoc log, containing
+# effective option at the time of generation and the reported logs.
+include-log: yes
+
+
+### Output options
+
+# The documented project's name.
+name: Pylearn
+
+# The CSS stylesheet for HTML output.  Can be the name of a builtin
+# stylesheet, or the name of a file.
+css: white
+
+# The documented project's URL.
+url: http://deeplearning.net/software/pylearn/
+
+# HTML code for the project link in the navigation bar.  If left
+# unspecified, the project link will be generated based on the
+# project's name and URL.
+#link: <a href="somewhere">My Cool Project</a>
+
+# The "top" page for the documentation.  Can be a URL, the name
+# of a module or class, or one of the special names "trees.html",
+# "indices.html", or "help.html"
+#top: os.path
+
+# An alternative help file.  The named file should contain the
+# body of an HTML file; navigation bars will be added to it.
+#help: my_helpfile.html
+
+# Whether or not to include a frames-based table of contents.
+#frames: yes
+frames: no
+
+# Whether each class should be listed in its own section when
+# generating LaTeX or PDF output.
+separate-classes: no
+
+
+### API linking options
+
+# Define a new API document.  A new interpreted text role
+# will be created
+#external-api: epydoc
+
+# Use the records in this file to resolve objects in the API named NAME.
+#external-api-file: epydoc:api-objects.txt
+
+# Use this URL prefix to configure the string returned for external API.
+#external-api-root: epydoc:http://epydoc.sourceforge.net/api
+# external-api: wiki doc
+# external-api-root: wiki:http://lgcm.iro.umontreal.ca/theano/wiki/ doc:http://lgcm.iro.umontreal.ca/auto_theano/doc/
+# external-api-file: wiki:wiki.idx doc:doc/doc.idx
+
+### Graph options
+
+# The list of graph types that should be automatically included
+# in the output.  Graphs are generated using the Graphviz "dot"
+# executable.  Graph types include: "classtree", "callgraph",
+# "umlclass".  Use "all" to include all graph types
+graph: all
+
+# The path to the Graphviz "dot" executable, used to generate
+# graphs.
+dotpath: /usr/bin/dot
+
+# The name of one or more pstat files (generated by the profile
+# or hotshot module).  These are used to generate call graphs.
+#pstat: autotest.pstat
+
+# Specify the font used to generate Graphviz graphs.
+# (e.g., helvetica or times).
+graph-font: Helvetica
+
+# Specify the font size used to generate Graphviz graphs.
+graph-font-size: 10
+
+
+### Return value options
+
+# The condition upon which Epydoc should exit with a non-zero
+# exit status. Possible values are error, warning, docstring_warning
+#fail-on: error
diff -r 08b37147dec1 -r 9472d234db2e doc/conf.py
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/conf.py	Thu Mar 18 11:33:49 2010 -0400
@@ -0,0 +1,191 @@
+# -*- coding: utf-8 -*-
+#
+# theano documentation build configuration file, created by
+# sphinx-quickstart on Tue Oct  7 16:34:06 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default value; values that are commented out
+# serve to show the default value.
+
+import sys, os
+
+# If your extensions are in another directory, add it here. If the directory
+# is relative to the documentation root, use os.path.abspath to make it
+# absolute, like shown here.
+#sys.path.append(os.path.abspath('some/directory'))
+
+# General configuration
+# ---------------------
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'ext']
+
+todo_include_todos = True
+
+try:
+    from sphinx.ext import pngmath
+    extensions.append('sphinx.ext.pngmath')
+except ImportError:
+    pass
+
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['.templates']
+
+# The suffix of source filenames.
+source_suffix = '.txt'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General substitutions.
+project = 'Theano'
+copyright = '2008--2009, LISA lab'
+
+# The default replacements for |version| and |release|, also used in various
+# other places throughout the built documents.
+#
+# The short X.Y version.
+version = '0.1'
+# The full version, including alpha/beta/rc tags.
+release = '0.1'
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# List of directories, relative to source directories, that shouldn't be searched
+# for source files.
+exclude_dirs = ['images', 'scripts', 'sandbox']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# Options for HTML output
+# -----------------------
+
+# The style sheet to use for HTML and HTML Help pages. A file of that name
+# must exist either in Sphinx' static/ path, or in one of the custom paths
+# given in html_static_path.
+#html_style = 'default.css'
+html_theme = 'sphinxdoc'
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (within the static path) to place at the top of
+# the sidebar.
+#html_logo = 'images/theano_logo-200x67.png'
+html_logo = 'images/theano_logo_allblue_200x46.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
+# pixels large.
+#html_favicon = None
+
+# 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', 'images']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+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
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_use_modindex = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, the reST sources are included in the HTML build as _sources/<name>.
+#html_copy_source = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'theanodoc'
+
+
+# Options for LaTeX output
+# ------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+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 = [
+  ('index', 'theano.tex', 'theano Documentation',
+   '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 = 'images/snake_theta2-trans.png'
+latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True
diff -r 08b37147dec1 -r 9472d234db2e doc/index.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/index.txt	Thu Mar 18 11:33:49 2010 -0400
@@ -0,0 +1,31 @@
+
+Welcome
+=======
+
+Pylearn is a Python library for machine learning, built on top of Theano, our 
+library for defining, optimizing and evaluating mathematical expressions
+involving multi-dimensional arrays.
+
+This documentation is under construction, but you can already access the
+automatically-generated API doc, along with more extensive explanations for 
+some modules.
+
+Download
+========
+
+We recommend the latest development version, available via::
+
+    hg clone http://hg.assembla.com/pylearn Pylearn
+
+The ``pylearn`` subfolder should be on your ``$PYTHONPATH``.
+
+Documentation
+=============
+
+For the moment, the following documentation is available.
+
+* `API <api/>`_ -- The automatically-generated API documentation
+
+You can download the latest `PDF documentation <http://deeplearning.net/software/pylearn/pylearn.pdf>`_, rather than reading it online.
+
+
diff -r 08b37147dec1 -r 9472d234db2e doc/scripts/docgen.py
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/scripts/docgen.py	Thu Mar 18 11:33:49 2010 -0400
@@ -0,0 +1,89 @@
+import sys
+import os
+import shutil
+import inspect
+
+from epydoc import docintrospecter 
+from epydoc.apidoc import RoutineDoc
+
+import getopt
+from collections import defaultdict
+
+if __name__ == '__main__':
+
+    # make sure we're in the right directory
+    this_file_directory = os.path.abspath(os.path.dirname(__file__))
+    pylearn_root = os.path.join(os.path.join(this_file_directory, ".."), "..")
+
+    #pylearn_root = "/".join(sys.path[0].split("/")[:-2])
+
+    options = defaultdict(bool)
+    options.update(dict([x, y or True] for x, y in getopt.getopt(sys.argv[1:], 'o:', ['epydoc', 'rst', 'help', 'nopdf'])[0]))
+    if options['--help']:
+        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)
+
+    options['--all'] = not (bool(options['--epydoc']) ^ bool(options['--rst']))
+
+    def mkdir(path):
+        try:
+            os.mkdir(path)
+        except OSError:
+            pass
+
+    outdir = options['-o'] or (pylearn_root + '/html')
+    mkdir(outdir)
+    os.chdir(outdir)
+    mkdir("doc")
+    mkdir("api")
+
+    # Make sure the appropriate 'theano' directory is in the PYTHONPATH
+    pythonpath = os.environ.get('PYTHONPATH', '')
+    pythonpath = pylearn_root + ':' + pythonpath
+    os.environ['PYTHONPATH'] = pythonpath
+
+    if options['--all'] or options['--epydoc']:
+        from epydoc.cli import cli
+        sys.path[0:0] = [pylearn_root]
+
+        #Generate HTML doc
+
+        ## This causes problems with the subsequent generation of sphinx doc
+        #sys.argv[:] = ['', '--config', '%s/doc/api/epydoc.conf' % pylearn_root, '-o', 'api']
+        #cli()
+        ## So we use this instead
+        os.system("epydoc --config %s/doc/api/epydoc.conf -o api" % pylearn_root)
+
+        # Generate PDF doc
+        # TODO
+
+    if options['--all'] or options['--rst']:
+        import sphinx
+        sys.path[0:0] = [os.path.join(pylearn_root, 'doc')]
+        sphinx.main(['', '-E', os.path.join(pylearn_root, 'doc'), '.'])
+
+        if not options['--nopdf']:
+            # Generate latex file in a temp directory
+            import tempfile
+            workdir = tempfile.mkdtemp()
+            sphinx.main(['', '-E', '-b', 'latex',
+                os.path.join(pylearn_root, 'doc'), workdir])
+            # Compile to PDF
+            os.chdir(workdir)
+            os.system('make')
+            try:
+                shutil.copy(os.path.join(workdir, 'pylearn.pdf'), outdir)
+                os.chdir(outdir)
+                shutil.rmtree(workdir)
+            except OSError, e:
+                print 'OSError:', e
+            except IOError, e:
+                print 'IOError:', e
+
+
+