[WIP] Attempt at fixing doc generation

.requirements.txt

@@ -1,4 +1,9 @@
 # This is for readthedocs.org to be able to build the documentation,
 # ignore otherwise
 numpydoc
-git+git://github.com/Theano/Theano.git
+numpy>=1.6.2
+scipy>=0.11
+
+--allow-external theano
+--allow-unverified theano
+git+https://github.com/Theano/Theano.git#egg=theano

doc/conf.py

@@ -17,6 +17,8 @@
 # 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'))
+pylearn2_path = os.path.join(os.path.dirname(__file__), os.pardir)
+sys.path.append(os.path.abspath(pylearn2_path))
 
 # General configuration
 # ---------------------

doc/scripts/docgen.py

@@ -11,7 +11,9 @@
 
 if __name__ == '__main__':
 
-    throot = "/".join(sys.path[0].split("/")[:-2])
+    # Equivalent of sys.path[0]/../..
+    throot = os.path.abspath(
+        os.path.join(sys.path[0], os.pardir, os.pardir))
 
     options = defaultdict(bool)
     options.update(dict([x, y or True] for x, y in getopt.getopt(sys.argv[1:], 'o:', ['epydoc', 'rst', 'help', 'nopdf', 'test'])[0]))
@@ -45,19 +47,19 @@ def mkdir(path):
     if options['--test']:
         import sphinx
         sys.path[0:0] = [os.path.join(throot, 'doc')]
-        out = sphinx.main(['', '-b' 'text', '-W',
-                           '-E', os.path.join(throot, 'doc'), '.'])
+        out = sphinx.build_main(['', '-b' 'text', '-W',
+                                 '-E', os.path.join(throot, 'doc'), '.'])
         sys.exit(out)
     elif options['--all'] or options['--rst']:
         import sphinx
         sys.path[0:0] = [os.path.join(throot, 'doc')]
-        sphinx.main(['', '-E', os.path.join(throot, 'doc'), '.'])
+        sphinx.build_main(['', '-E', os.path.join(throot, 'doc'), '.'])
 
         if not options['--nopdf']:
             # Generate latex file in a temp directory
             import tempfile
             workdir = tempfile.mkdtemp()
-            sphinx.main(['', '-E', '-b', 'latex',
+            sphinx.build_main(['', '-E', '-b', 'latex',
                 os.path.join(throot, 'doc'), workdir])
             # Compile to PDF
             os.chdir(workdir)

pylearn2/datasets/hdf5.py

@@ -277,15 +277,15 @@ def get(self, sources, indexes):
         """
         Retrieves the requested elements from the dataset.
 
-        Parameter
-        ---------
+        Parameters
+        ----------
         sources : tuple
             A tuple of source identifiers
         indexes : slice or list
             A slice or a list of indexes
 
-        Return
-        ------
+        Returns
+        -------
         rval : tuple
             A tuple of batches, one for each source
         """
@@ -329,8 +329,8 @@ def get_num_examples(self, source_or_alias=None):
         returing a list of num_examples. Do not rely on this function unless
         unavoidable.
 
-        Parameter
-        ---------
+        Parameters
+        ----------
         source_or_alias : str, optional
             The source you want the number of examples of
         """
@@ -363,8 +363,8 @@ def __getitem__(self, key_or_alias):
         """
         Returns the item corresponding to a key or an alias.
 
-        Parameter
-        ---------
+        Parameters
+        ----------
         key_or_alias: any valid key for a dictionary
             A key or an alias.
         """
@@ -379,8 +379,8 @@ def __setitem__(self, keys, value):
         """
         Add an element to the dictionary
 
-        Parameter
-        ---------
+        Parameters
+        ----------
         keys: either a tuple `(key, alias)` or any valid key for a dictionary
             The key and optionally the alias of the new element.
         value: any input accepted as value by a dictionary
@@ -419,8 +419,8 @@ def set_alias(self, key, alias):
         Add an alias to a key of the dictionary that doesn't have already an
         alias.
 
-        Parameter
-        ---------
+        Parameters
+        ----------
         keys: any valid key for a dictionary
            A key of the dictionary.
         alias: any input accepted as key by a dictionary
@@ -446,8 +446,8 @@ def __contains__(self, key_or_alias):
         """
         Returns true if the key or alias is an element of the dictionary
 
-        Parameter
-        ---------
+        Parameters
+        ----------
         keys_or_alias: any valid key for a dictionary
             The key or the alias to look for.
         """

pylearn2/gui/get_weights_report.py

@@ -36,9 +36,9 @@ def get_weights_report(model_path=None,
     rescale : str
         A string specifying how to rescale the filter images:
             - 'individual' (default) : scale each filter so that it
-                  uses as much as possible of the dynamic range
-                  of the display under the constraint that 0
-                  is gray and no value gets clipped
+              uses as much as possible of the dynamic range
+              of the display under the constraint that 0
+              is gray and no value gets clipped
             - 'global' : scale the whole ensemble of weights
             - 'none' :   don't rescale
     dataset : pylearn2.datasets.dataset.Dataset

pylearn2/models/s3c.py

@@ -282,23 +282,22 @@ class S3C(Model, Block):
     local_rf_src : Dataset, optional
         if not None, it should be a dataset.
         it requires the following other params:
-
-        - local_rf_shape : a 2 tuple
-        - One of:
-
-            - local_rf_stride: a 2 tuple or None
-                if specified, pull out patches on a regular grid
-            - local_rf_max_shape: a 2 tuple or None
-                if specified, pull out patches of random shape and
-                location
-            - local_rf_draw_patches : WRITEME
-                if true, local receptive fields are patches from
-                local_rf_src. otherwise, they're random patches.
-                will initialize the weights to have only local
-                receptive fields. (won't make a sparse matrix or
-                anything like that)
+        - `local_rf_shape` : a 2 tuple
+        - One of `local_rf_stride`, `local_rf_max_shape`, `local_rf_draw_patches`
 
         incompatible with random_patches_src for now
+    local_rf_shape : a 2 tuple
+    local_rf_stride: a 2 tuple or None
+        if specified, pull out patches on a regular grid
+    local_rf_max_shape: a 2 tuple or None
+        if specified, pull out patches of random shape and
+        location
+    local_rf_draw_patches : WRITEME
+        if true, local receptive fields are patches from
+        local_rf_src. otherwise, they're random patches.
+        will initialize the weights to have only local
+        receptive fields. (won't make a sparse matrix or
+        anything like that)
     init_unit_W : bool
         if True, initializes weights with unit norm
     """

pylearn2/training_algorithms/sgd.py

@@ -898,19 +898,21 @@ class EpochMonitor(object):
     monitor_rate : int (optional)
         Call full monitor updates within epochs every `monitor_rate` batches
 
-    YAML usage
-    ----------
-    model: &model !obj:pylearn2.models.mlp.MLP {
-        ...
-    },
-    algorithm: !obj:pylearn2.training_algorithms.sgd.SGD {
-        update_callbacks: [
-            !obj:pylearn2.training_algorithms.sgd.EpochMonitor {
-                model: *model,
-                tick_rate: 20,
-                monitor_rate: 110 }],
-        ...
-    }
+    Examples
+    --------
+    YAML usage::
+
+        model: &model !obj:pylearn2.models.mlp.MLP {
+            ...
+        },
+        algorithm: !obj:pylearn2.training_algorithms.sgd.SGD {
+            update_callbacks: [
+                !obj:pylearn2.training_algorithms.sgd.EpochMonitor {
+                    model: *model,
+                    tick_rate: 20,
+                    monitor_rate: 110 }],
+            ...
+        }
     """
     def __init__(self, model, tick_rate=None, monitor_rate=None):
         self.model = model

setup.py

@@ -1,11 +1,16 @@
 from __future__ import print_function
 
+import sys
 import warnings
 from setuptools import setup, find_packages, Extension
 from setuptools.command.install import install
 import numpy
 
-from theano.compat.six.moves import input
+# Importing theano.compat.six.moves.input may not work here,
+# because the dependencies may not have been installed yet.
+PY3 = sys.version_info[0] == 3
+if not PY3:
+    input = raw_input
 
 # Because many people neglected to run the pylearn2/utils/setup.py script
 # separately, we compile the necessary Cython extensions here but because