doc works fine

__transit/scripts/gen_typelist.py

-
-from gen_oplist import print_title, print_hline
-
-
-if __name__ == '__main__':
-    print_title("Type List", "~", "~")
-
-    print "*THIS PAGE IS A PLACEHOLDER: WRITEME*"
-    print ""
-    print_hline()
-
-    print ""
-    print ".. contents::"
-    print ""
-
-    print_title("Type Classes", '=')
-
-    print "- scalar.Scalar\n"
-    print "- tensor.Tensor\n"
-    print "- sparse.Sparse\n"
-
-    print_title("Type Instances", '=')
-
-    print "- scalar.int8\n"
-    print "- tensor.lvector\n"
-    print "- sparse.??\n"
-
-    print ""
-
-    for line in open("doc/header.txt"):
-        print line[:-1]

doc/conf.py

@@ -36,7 +36,7 @@ master_doc = 'index'
 
 # General substitutions.
 project = 'theano'
-copyright = '2008, Olivier Breuleux, James Bergstra'
+copyright = '2008, LISA lab'
 
 # The default replacements for |version| and |release|, also used in various
 # other places throughout the built documents.

doc/ext.py

 
+import re
 import os
-from docutils import nodes
+from docutils import nodes, utils
+from docutils.parsers.rst import roles
 import epydoc.docwriter.xlink as xlink
 
 def role_fn(name, rawtext, text, lineno, inliner,
@@ -9,14 +11,57 @@ def role_fn(name, rawtext, text, lineno, inliner,
     return [node], []
 
 
+_TARGET_RE = re.compile(r'^(.*?)\s*<(?:URI:|URL:)?([^<>]+)>$') 
+def create_api_role(name, problematic):
+    """
+    Create and register a new role to create links for an API documentation.
+
+    Create a role called `name`, which will use the URL resolver registered as
+    ``name`` in `api_register` to create a link for an object.
+
+    :Parameters:
+      `name` : `str`
+        name of the role to create.
+      `problematic` : `bool`
+        if True, the registered role will create problematic nodes in
+        case of failed references. If False, a warning will be raised
+        anyway, but the output will appear as an ordinary literal.
+    """
+    def resolve_api_name(n, rawtext, text, lineno, inliner,
+                options={}, content=[]):
+
+        # Check if there's separate text & targets 
+        m = _TARGET_RE.match(text) 
+        if m: text, target = m.groups() 
+        else: target = text 
+        
+        # node in monotype font
+        text = utils.unescape(text)
+        node = nodes.literal(rawtext, text, **options)
+
+        # Get the resolver from the register and create an url from it.
+        try:
+            url = xlink.api_register[name].get_url(target)
+        except IndexError, exc:
+            msg = inliner.reporter.warning(str(exc), line=lineno)
+            if problematic:
+                prb = inliner.problematic(rawtext, text, msg)
+                return [prb], [msg]
+            else:
+                return [node], []
+
+        if url is not None:
+            node = nodes.reference(rawtext, '', node, refuri=url, **options)
+        return [node], []
+
+    roles.register_local_role(name, resolve_api_name)
+
+
 def setup(app):
-    help(xlink)
-    #role = xlink.create_api_role('api', True)
-    #print role
 
-    xlink.register_api('api', xlink.DocUrlGenerator())
     xlink.set_api_file('api', os.path.join(app.outdir, 'api', 'api-objects.txt'))
     xlink.set_api_root('api', os.path.join(app.outdir, 'api', ''))
-    xlink.create_api_role('api', True)
+    #xlink.create_api_role('api', True)
+    create_api_role('api', True)
 
     app.add_role("wiki", role_fn)

scripts/docgen.py

@@ -59,6 +59,16 @@ if __name__ == '__main__':
 
     throot = "/".join(sys.path[0].split("/")[:-1])
 
+    import gen_oplist
+    print 'Generating oplist...'
+    gen_oplist.print_file(open('%s/doc/doc/oplist.txt' % throot, 'w'))
+    print 'oplist done!'
+
+    import gen_typelist
+    print 'Generating typelist...'
+    gen_typelist.print_file(open('%s/doc/doc/typelist.txt' % throot, 'w'))
+    print 'typelist done!'
+
     os.chdir(throot)
 
     def mkdir(path):
@@ -81,6 +91,6 @@ if __name__ == '__main__':
     if len(sys.argv) == 1 or sys.argv[1] != 'epydoc':
         import sphinx
         sys.path[0:0] = [os.path.realpath('doc')]
-        sphinx.main(['', 'doc', 'html'])
+        sphinx.main(['', '-E', 'doc', 'html'])
 
 

__transit/scripts/gen_oplist.py → scripts/gen_oplist.py

 """script to generate doc/oplist.txt, which compiles to :doc:`oplist`. """
 __docformat__ = "restructuredtext en"
-import sys
+import sys, os
+theano_path = os.path.realpath("%s/.." % sys.path[0])
+sys.path[0:0] = [theano_path]
+
 from theano import gof
 
-def print_title(title_string, under_char, over_char=''):
+def print_title(file, title_string, under_char, over_char=''):
     l = len(title_string)
     if over_char:
-        print over_char * l
+        print >>file, over_char * l
 
-    print title_string
+    print >>file, title_string
 
     if under_char:
-        print under_char * l
+        print >>file, under_char * l
 
-    print ""
+    print >>file, ""
 
-def print_hline():
-    print '-' * 80
+def print_hline(file):
+    print >>file, '-' * 80
 
 class Entry:
     """Structure for generating the oplist file"""
@@ -31,7 +34,7 @@ class Entry:
         self.name = name
         self.module = symbol.__module__ #current_module.__name__ # symbol.__module__
         self.docstring = symbol.__doc__
-        self.tags = ['module:%s' % current_module.__name__] + getattr(symbol, '__oplist_tags', [])
+        self.tags = ['%s' % current_module.__name__] + getattr(symbol, '__oplist_tags', [])
 
     def mini_desc(self, maxlen=50):
         """Return a short description of the op"""
@@ -73,7 +76,7 @@ class Entry:
         else:
             return "%s ..."% chomp(self.docstring[:maxlen-minmax])
 
-    apilink = property(lambda self: ":api:`%s.%s`"% (self.module, self.name))
+    apilink = property(lambda self: ":api:`%s <%s.%s>`"% (self.name, self.module, self.name))
     """Return the ReST link into the epydoc of this symbol"""
 
 class EntryOp(Entry):
@@ -126,51 +129,63 @@ def search_entries(module_list, ops = None, constructors = None, seen = None):
 
     return ops, constructors
 
-def print_entries(ops, constructors):
+def print_entries(file, ops, constructors):
     tags = {}
     for o in ops + constructors:
         for t in o.tags:
             tags.setdefault(t, []).append(o)
 
     for t in tags:
-        print_title(t, '=')
+        print_title(file, t, '=')
 
         tagged_ops = [op for op in tags[t] if isinstance(op, EntryOp)]
         if len(tagged_ops):
-            print_title('Op Classes', '-')
+            print_title(file, 'Op Classes', '-')
             for op in tagged_ops:
-                print "- %s" % op.apilink
-                print "  %s" % op.mini_desc()
-                print ""
+                print >>file, "- %s" % op.apilink
+                print >>file, "  %s" % op.mini_desc()
+                print >>file, ""
 
         tagged_ops = [op for op in tags[t] if isinstance(op, EntryConstructor)]
         if len(tagged_ops):
-            print_title('Op Constructors', '-')
+            print_title(file, 'Op Constructors', '-')
             for op in tagged_ops:
-                print "- %s" % op.apilink
-                print "  %s" % op.mini_desc()
-                print ""
+                print >>file, "- %s" % op.apilink
+                print >>file, "  %s" % op.mini_desc()
+                print >>file, ""
 
 
-if __name__ == "__main__":
-    """Generate the op list"""
-    import theano
+def print_file(file):
 
-    print_title("Op List", "~", "~")
-    print """
+    print_title(file, "Op List", "~", "~")
+    print >>file, """
 This page lists the `Op Classes` and `constructors` that are provided by the Theano library.
 `Op Classes` drive from :api:`Op`, whereas `constructors` are typically `Op Class` instances, but may be true Python functions.
 
 In the future, this list may distinguish `constructors` that are Op instances from true Python functions.
 
 """
-    print_hline()
-    print ""
-    print ".. contents:: "
-    print ""
+    print_hline(file)
+    print >>file, ""
+    print >>file, ".. contents:: "
+    print >>file, ""
 
     ops, constructors = search_entries([theano])
 
-    print_entries(ops, constructors)
+    print_entries(file, ops, constructors)
+
+    print >>file, ""
+    
+
+import theano
+
+if __name__ == "__main__":
+    """Generate the op list"""
+
+    if len(sys.argv) >= 2:
+        file = open(sys.argv[1], 'w')
+    else:
+        file = sys.stdout
+
+    print_file(file)
 
-    print ""

scripts/gen_typelist.py

+
+from gen_oplist import print_title, print_hline
+
+
+def print_file(file):
+
+    print_title(file, "Type List", "~", "~")
+
+    print >>file, "*THIS PAGE IS A PLACEHOLDER: WRITEME*"
+    print >>file, ""
+    print_hline(file)
+
+    print >>file, ""
+    print >>file, ".. contents::"
+    print >>file, ""
+
+    print_title(file, "Type Classes", '=')
+
+    print >>file, "- scalar.Scalar\n"
+    print >>file, "- tensor.Tensor\n"
+    print >>file, "- sparse.Sparse\n"
+
+    print_title(file, "Type Instances", '=')
+
+    print >>file, "- scalar.int8\n"
+    print >>file, "- tensor.lvector\n"
+    print >>file, "- sparse.??\n"
+
+    print >>file, ""
+
+
+if __name__ == '__main__':
+
+    if len(sys.argv) >= 2:
+        file = open(sys.argv[1], 'w')
+    else:
+        file = sys.stdout
+
+    print_file(file)

theano/tensor/basic.py

@@ -567,7 +567,7 @@ def _redefine(real_symbol_value, module='tensor'):
     
     This is useful to trick epydoc into doing what we want.  It's a hack.
     """
-    real_symbol_value.__module__ = 'tensor'
+    real_symbol_value.__module__ = 'tensor.basic'
     def decorator(f):
         return real_symbol_value
     return decorator