Add a mode to docgen to run the code samples in the documentation.

doc/cifarSC2011/advanced_theano.txt

@@ -16,46 +16,55 @@ Conditions
 
 **IfElse Example: Comparison with Switch**
 
-.. code-block:: python
+.. testcode::
 
-  from theano import tensor as T
-  from theano.ifelse import ifelse
-  import theano, time, numpy
+   from theano import tensor as T
+   from theano.ifelse import ifelse
+   import theano, time, numpy
 
-  a,b = T.scalars('a','b')
-  x,y = T.matrices('x','y')
-  
-  z_switch = T.switch(T.lt(a,b), T.mean(x), T.mean(y))
-  z_lazy = ifelse(T.lt(a,b), T.mean(x), T.mean(y))
+   a,b = T.scalars('a','b')
+   x,y = T.matrices('x','y')
+
+   z_switch = T.switch(T.lt(a,b), T.mean(x), T.mean(y))
+   z_lazy = ifelse(T.lt(a,b), T.mean(x), T.mean(y))
+
+   f_switch = theano.function([a,b,x,y], z_switch,
+                              mode=theano.Mode(linker='vm'))
+   f_lazyifelse = theano.function([a,b,x,y], z_lazy,
+                                  mode=theano.Mode(linker='vm'))
+
+   val1 = 0.
+   val2 = 1.
+   big_mat1 = numpy.ones((10000,1000))
+   big_mat2 = numpy.ones((10000,1000))
 
-  f_switch = theano.function([a,b,x,y], z_switch, 
-                      mode=theano.Mode(linker='vm'))
-  f_lazyifelse = theano.function([a,b,x,y], z_lazy,
-                      mode=theano.Mode(linker='vm'))
+   n_times = 10
 
-  val1 = 0.
-  val2 = 1.
-  big_mat1 = numpy.ones((10000,1000))
-  big_mat2 = numpy.ones((10000,1000))
+   tic = time.clock()
+   for i in xrange(n_times):
+       f_switch(val1, val2, big_mat1, big_mat2)
+   print 'time spent evaluating both values %f sec'%(time.clock()-tic)
 
-  n_times = 10
+   tic = time.clock()
+   for i in xrange(n_times):
+       f_lazyifelse(val1, val2, big_mat1, big_mat2)
+   print 'time spent evaluating one value %f sec'%(time.clock()-tic)
 
-  tic = time.clock()
-  for i in xrange(n_times):
-      f_switch(val1, val2, big_mat1, big_mat2)
-  print 'time spent evaluating both values %f sec'%(time.clock()-tic)
+.. testoutput::
+   :hide:
+   :options: +ELLIPSIS
 
-  tic = time.clock()
-  for i in xrange(n_times):
-      f_lazyifelse(val1, val2, big_mat1, big_mat2)
-  print 'time spent evaluating one value %f sec'%(time.clock()-tic)
+   time spent evaluating both values ... sec
+   time spent evaluating one value ... sec
 
 IfElse Op spend less time (about an half) than Switch since it computes only
 one variable instead of both.
 
->>> python ifelse_switch.py
-time spent evaluating both values 0.6700 sec
-time spent evaluating one value 0.3500 sec
+.. code-block:: none
+
+  $ python ifelse_switch.py
+  time spent evaluating both values 0.6700 sec
+  time spent evaluating one value 0.3500 sec
 
 Note that IfElse condition is a boolean while Switch condition is a tensor, so
 Switch is more general.
@@ -112,7 +121,7 @@ Loops
 
 **Scan Example: Calculating a Polynomial**
 
-.. code-block:: python
+.. testcode::
 
   import theano
   import theano.tensor as T
@@ -133,7 +142,10 @@ Loops
 
   test_coeff = numpy.asarray([1, 0, 2], dtype=numpy.float32)
   print calculate_polynomial(test_coeff, 3)
-  # 19.0
+
+.. testoutput::
+
+  19.0
 
 
 
@@ -267,7 +279,7 @@ Printing/Drawing Theano graphs
 
 ``theano.printing.pprint(variable)``
 
->>> theano.printing.pprint(prediction)
+>>> theano.printing.pprint(prediction) # doctest: +SKIP
 gt((TensorConstant{1} / (TensorConstant{1} + exp(((-(x \\dot w)) - b)))),TensorConstant{0.5})
 
 
@@ -275,7 +287,7 @@ gt((TensorConstant{1} / (TensorConstant{1} + exp(((-(x \\dot w)) - b)))),TensorC
 
 ``theano.printing.debugprint({fct, variable, list of variables})``
 
->>> theano.printing.debugprint(prediction)
+>>> theano.printing.debugprint(prediction) # doctest: +SKIP
 Elemwise{gt,no_inplace} [@181772236] ''
  |Elemwise{true_div,no_inplace} [@181746668] ''
  | |InplaceDimShuffle{x} [@181746412] ''
@@ -293,7 +305,7 @@ Elemwise{gt,no_inplace} [@181772236] ''
  | | | | | |b [@181730156]
  |InplaceDimShuffle{x} [@181771788] ''
  | |TensorConstant{0.5} [@181771148]
->>> theano.printing.debugprint(predict)
+>>> theano.printing.debugprint(predict) # doctest: +SKIP
 Elemwise{Composite{neg,{sub,{{scalar_sigmoid,GT},neg}}}} [@183160204] ''   2
  |dot [@183018796] ''   1
  | |x [@183000780]
@@ -304,19 +316,19 @@ Elemwise{Composite{neg,{sub,{{scalar_sigmoid,GT},neg}}}} [@183160204] ''   2
 
 - Picture Printing of Graphs
 
->>> theano.printing.pydotprint_variables(prediction)
+>>> theano.printing.pydotprint_variables(prediction) # doctest: +SKIP
 
 .. image:: ../hpcs2011_tutorial/pics/logreg_pydotprint_prediction.png
    :width: 800 px
 
 All pydotprint* requires graphviz and pydot
 
->>> theano.printing.pydotprint(predict)
+>>> theano.printing.pydotprint(predict) # doctest: +SKIP
 
 .. image:: ../hpcs2011_tutorial/pics/logreg_pydotprint_predic.png
    :width: 800 px
 
->>> theano.printing.pydotprint(train) # This is a small train example!
+>>> theano.printing.pydotprint(train) # This is a small train example! # doctest: +SKIP
 
 .. image:: ../hpcs2011_tutorial/pics/logreg_pydotprint_train.png
    :width: 1500 px

doc/cifarSC2011/pyCUDA.txt

@@ -80,7 +80,7 @@ Exercise 6
 Theano + PyCUDA
 ---------------
 
-.. code-block:: python
+.. testcode::
 
     import numpy, theano
     import theano.misc.pycuda_init
@@ -118,15 +118,20 @@ Theano + PyCUDA
                 pycuda_fct(inputs[0][0], z[0], numpy.intc(inputs[0][0].size),
                            block=(512,1,1), grid=grid)
             return thunk
-    
+
+.. testoutput::
+   :hide:
+   :options: +SKIP
+
+   This contains GPU code so skip it
 
 Test it!
 
->>> x = theano.tensor.fmatrix()
->>> f = theano.function([x], PyCUDADoubleOp()(x))
->>> xv=numpy.ones((4,5), dtype="float32")
->>> assert numpy.allclose(f(xv), xv*2)
->>> print numpy.asarray(f(xv))
+>>> x = theano.tensor.fmatrix() # doctest: +SKIP
+>>> f = theano.function([x], PyCUDADoubleOp()(x)) # doctest: +SKIP
+>>> xv=numpy.ones((4,5), dtype="float32") # doctest: +SKIP
+>>> assert numpy.allclose(f(xv), xv*2) # doctest: +SKIP
+>>> print numpy.asarray(f(xv)) # doctest: +SKIP
 
 Exercises 7
 -----------

doc/conf.py

@@ -23,7 +23,7 @@
 
 # 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']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.doctest']
 
 todo_include_todos = True
 

doc/glossary.txt

@@ -3,6 +3,11 @@
 Glossary
 ========
 
+..
+    # This is for the doctests in the file
+    >>> import theano
+    >>> from theano import tensor
+
 .. glossary::
 
     Apply
@@ -25,8 +30,10 @@ Glossary
     Constant
         A variable with an immutable value.
         For example, when you type
+
         >>> x = tensor.ivector()
         >>> y = x + 3
+
         Then a `constant` is created to represent the ``3`` in the graph.
 
         See also: :class:`gof.Constant`

doc/install.txt

@@ -318,7 +318,7 @@ a Python (or IPython) interpreter,
 .. code-block:: python
 
     >>> import theano
-    >>> theano.test()
+    >>> theano.test() # doctest: +SKIP
 
 You can also run them in-place from the Git checkout directory by typing
 

doc/scripts/docgen.py

@@ -65,7 +65,7 @@ if __name__ == '__main__':
     options.update(dict([x, y or True] for x, y in
         getopt.getopt(sys.argv[1:],
                       'o:',
-                      ['epydoc', 'rst', 'help', 'nopdf', 'cache'])[0]))
+                      ['epydoc', 'rst', 'help', 'nopdf', 'cache', 'test'])[0]))
     if options['--help']:
         print 'Usage: %s [OPTIONS]' % sys.argv[0]
         print '  -o <dir>: output the html files in the specified dir'
@@ -74,10 +74,11 @@ if __name__ == '__main__':
         print '  --nopdf: do not produce a PDF file from the doc, only HTML'
         print '  --epydoc: only compile the api documentation',
         print '(requires epydoc)'
+        print '  --test: run all the code samples in the documentaton'
         print '  --help: this help'
         sys.exit(0)
 
-    if not (options['--epydoc'] or options['--rst']):
+    if not (options['--epydoc'] or options['--rst'] or options['--test']):
         # Default is now rst
         options['--rst'] = True
 
@@ -113,17 +114,18 @@ if __name__ == '__main__':
         # Generate PDF doc
         # TODO
 
+    def call_sphinx(builder, workdir, extraopts=None):
+        import sphinx
+        if extraopts is None:
+            extraopts = []
+        if not options['--cache']:
+            extraopts.append('-E')
+        sphinx.main(['', '-b', builder] + extraopts +
+                    [os.path.join(throot, 'doc'), workdir])
+
     if options['--all'] or options['--rst']:
         mkdir("doc")
         sys.path[0:0] = [os.path.join(throot, 'doc')]
-        def call_sphinx(builder, workdir, extraopts=None):
-            import sphinx
-            if extraopts is None:
-                extraopts = []
-            if not options['--cache']:
-                extraopts.append('-E')
-            sphinx.main(['', '-b', builder] + extraopts +
-                        [os.path.join(throot, 'doc'), workdir])
         call_sphinx('html', '.')
 
         if not options['--nopdf']:
@@ -142,3 +144,8 @@ if __name__ == '__main__':
                 print 'OSError:', e
             except IOError, e:
                 print 'IOError:', e
+
+    if options['--test']:
+        mkdir("doc")
+        sys.path[0:0] = [os.path.join(throot, 'doc')]
+        call_sphinx('doctest', '.')

theano/tensor/subtensor.py

@@ -967,6 +967,7 @@ def set_subtensor(x, y, inplace=False,
 
     Example: To replicate the numpy expression "r[10:] = 5", type
 
+    >>> r = ivector()
     >>> new_r = set_subtensor(r[10:], 5)
 
     :param x: symbolic variable for the lvalue of = operation
@@ -991,6 +992,7 @@ def inc_subtensor(x, y, inplace=False, set_instead_of_inc=False,
 
     Example: To replicate the numpy expression "r[10:] += 5", type
 
+    >>> r = ivector()
     >>> new_r = inc_subtensor(r[10:], 5)
     """
     # First of all, y cannot have a higher dimension than x,

theano/tests/test_tutorial.py

@@ -892,7 +892,7 @@ class T_loading_and_saving(unittest.TestCase):
 
 
 class T_modes(unittest.TestCase):
-    # All tests here belog to
+    # All tests here belong to
     # http://deeplearning.net/software/theano/tutorial/modes.html
     # Theano/doc/tutorial/modes.txt
     # Any change you do here also add it to the tutorial !