]> git.ipfire.org Git - thirdparty/sqlalchemy/sqlalchemy.git/commitdiff
added pre-compiled docstring support
authorMike Bayer <mike_mp@zzzcomputing.com>
Fri, 12 May 2006 19:25:41 +0000 (19:25 +0000)
committerMike Bayer <mike_mp@zzzcomputing.com>
Fri, 12 May 2006 19:25:41 +0000 (19:25 +0000)
doc/build/compile_docstrings.py [new file with mode: 0644]
doc/build/components/pydoc.myt
doc/build/content/docstrings.myt
doc/build/genhtml.py
doc/build/lib/docstring.py [new file with mode: 0644]
doc/build/runhtml.py

diff --git a/doc/build/compile_docstrings.py b/doc/build/compile_docstrings.py
new file mode 100644 (file)
index 0000000..fb95273
--- /dev/null
@@ -0,0 +1,31 @@
+import cPickle as pickle
+import sys, os
+
+sys.path = ['../../lib', './lib/'] + sys.path
+
+import docstring
+
+import sqlalchemy.schema as schema
+import sqlalchemy.engine as engine
+import sqlalchemy.sql as sql
+import sqlalchemy.pool as pool
+import sqlalchemy.mapping as mapping
+import sqlalchemy.exceptions as exceptions
+import sqlalchemy.ext.proxy as proxy
+
+objects = []
+def make_doc(obj, classes=None, functions=None):
+    objects.append(docstring.ObjectDoc(obj, classes=classes, functions=functions))
+    
+make_doc(obj=schema)
+make_doc(obj=engine, classes=[engine.SQLSession, engine.SQLEngine, engine.ResultProxy, engine.RowProxy])
+make_doc(obj=sql, classes=[sql.ClauseParameters, sql.Compiled, sql.ClauseElement, sql.TableClause, sql.ColumnClause])
+make_doc(obj=pool, classes=[pool.DBProxy, pool.Pool, pool.QueuePool, pool.SingletonThreadPool])
+make_doc(obj=mapping, classes=[mapping.Mapper, mapping.MapperExtension])
+make_doc(obj=mapping.query, classes=[mapping.query.Query])
+make_doc(obj=mapping.objectstore, classes=[mapping.objectstore.Session, mapping.objectstore.Session.SessionTrans])
+make_doc(obj=exceptions)
+make_doc(obj=proxy)
+
+output = os.path.join(os.getcwd(), 'content', "compiled_docstrings.pickle")
+pickle.dump(objects, file(output, 'w'))
\ No newline at end of file
index 442403513ad88e547f6c8258d1b369bd2beacef2..989ea2199cf48fa40af569f0c1cfa17eaec03b91 100644 (file)
 <%global>
-    import re, types
+    import re, types, string, docstring
     def format_paragraphs(text):
-        return re.sub(r'([\w ])\n([\w ])', r'\1 \2', text or '', re.S)
+        return re.sub(r'([\w])\n([\w])', r'\1 \2', text or '', re.S)
 </%global>
 
 <%method obj_doc>
     <%args>
         obj
-        functions = None
-        classes = None
     </%args>
-    <%init>
-        import types
-        isclass = isinstance(obj, types.ClassType) or isinstance(obj, types.TypeType)
-        name= obj.__name__
-        
-        if not isclass:
-            if hasattr(obj, '__all__'):
-                objects = obj.__all__
-                sort = True
-            else:
-                objects = obj.__dict__.keys()
-                sort = True
-            if functions is None:
-                functions = [getattr(obj, x, None) 
-                    for x in objects 
-                    if getattr(obj,x,None) is not None and 
-                        (isinstance(getattr(obj,x), types.FunctionType))
-                        and not getattr(obj,x).__name__[0] == '_'
-                    ]
-                if sort:
-                    functions.sort(lambda a, b: cmp(a.__name__, b.__name__))
-            if classes is None:
-                classes = [getattr(obj, x, None) 
-                    for x in objects 
-                    if getattr(obj,x,None) is not None and 
-                        (isinstance(getattr(obj,x), types.TypeType) 
-                        or isinstance(getattr(obj,x), types.ClassType))
-                        and not getattr(obj,x).__name__[0] == '_'
-                    ]
-                if sort:
-                    classes.sort(lambda a, b: cmp(a.__name__, b.__name__))
-        else:
-            if functions is None:
-                functions = (
-                    [getattr(obj, x).im_func for x in obj.__dict__.keys() if isinstance(getattr(obj,x), types.MethodType) 
-                    and 
-                    (getattr(obj, x).__name__ == '__init__' or not getattr(obj,x).__name__[0] == '_')
-                    ] + 
-                    [(x, getattr(obj, x)) for x in obj.__dict__.keys() if isinstance(getattr(obj,x), property) 
-                    and 
-                    not x[0] == '_'
-                    ]
-                 )
-                functions.sort(lambda a, b: cmp(getattr(a, '__name__', None) or a[0], getattr(b, '__name__', None) or b[0] ))
-            if classes is None:
-                classes = []
-            
-        if isclass:
-            description = "Class " + name
-            if hasattr(obj, '__mro__'):
-                description += "(" + obj.__mro__[1].__name__ + ")"
-        else:
-            description = "Module " + name
-    </%init>
-
-<&|doclib.myt:item, name=obj.__name__, description=description &>
-<&|formatting.myt:formatplain&><% format_paragraphs(obj.__doc__) %></&>
+    
+<&|doclib.myt:item, name=obj.name, description=obj.description &>
+<&|formatting.myt:formatplain&><% format_paragraphs(obj.doc) %></&>
 
-% if not isclass and len(functions):
+% if not obj.isclass and obj.functions:
 <&|doclib.myt:item, name="modfunc", description="Module Functions" &>
 <&|formatting.myt:paramtable&>
-%   for func in functions:
+%   for func in obj.functions:
     <& SELF:function_doc, func=func &>
 %
 </&>
 </&>
 % else:
-% if len(functions):
+% if obj.functions:
 <&|formatting.myt:paramtable&>
-%   for func in functions:
-%   if isinstance(func, types.FunctionType):
+%   for func in obj.functions:
+%   if isinstance(func, docstring.FunctionDoc):
     <& SELF:function_doc, func=func &>
-%   elif isinstance(func, tuple):
-    <& SELF:property_doc, name = func[0], prop=func[1] &>
+%   elif isinstance(func, docstring.PropertyDoc):
+    <& SELF:property_doc, prop=func &>
 %
 %
 </&>
 %
 %
 
-% if len(classes):
+% if obj.classes:
 <&|formatting.myt:paramtable&>
-%   for class_ in classes:
+%   for class_ in obj.classes:
       <& SELF:obj_doc, obj=class_ &>
 %   
 </&>
 %    
 </&>
 
-
 </%method>
 
 <%method function_doc>
     <%args>func</%args>
-    <%init>
-        import inspect
-        argspec = inspect.getargspec(func)
-        argnames = argspec[0]
-        varargs = argspec[1]
-        varkw = argspec[2]
-        defaults = argspec[3] or ()
-        argstrings = []
-        for i in range(0, len(argnames)):
-            if i >= len(argnames) - len(defaults):
-                argstrings.append("%s=%s" % (argnames[i], repr(defaults[i - (len(argnames) - len(defaults))])))
-            else:
-                argstrings.append(argnames[i])
-        if varargs is not None:
-           argstrings.append("*%s" % varargs)
-        if varkw is not None:
-           argstrings.append("**%s" % varkw)
-    </%init>
-    
-    <&|formatting.myt:function_doc, name="def " + func.__name__, link=func.__name__, arglist=argstrings &>
-    <&|formatting.myt:formatplain&><% format_paragraphs(func.__doc__) %></&>
+    <&|formatting.myt:function_doc, name=func.name, link=func.link, arglist=func.arglist &>
+    <&|formatting.myt:formatplain&><% format_paragraphs(func.doc) %></&>
     </&>
 </%method>
 
 
 <%method property_doc>
     <%args>
-        name
         prop
     </%args>
-    <&|formatting.myt:member_doc, name=name + " = property()", link=name &>
-    <&|formatting.myt:formatplain&><% format_paragraphs(prop.__doc__) %></&>
+    <&|formatting.myt:member_doc, name=prop.name, link=prop.link &>
+    <&|formatting.myt:formatplain&><% format_paragraphs(prop.doc) %></&>
     </&>    
 </%method>
\ No newline at end of file
index 1e157b6aae545b6c255f48b6f4b855ee39705e73..a30a5fb636d49dd8f47e6a390bf0236fff2a47e2 100644 (file)
@@ -2,24 +2,14 @@
 <%attr>title='Modules and Classes'</%attr>
 <&|doclib.myt:item, name="docstrings", description="Modules and Classes" &>
 <%init>
-    import sqlalchemy.schema as schema
-    import sqlalchemy.engine as engine
-    import sqlalchemy.sql as sql
-    import sqlalchemy.pool as pool
-    import sqlalchemy.mapping as mapping
-    import sqlalchemy.exceptions as exceptions
-    import sqlalchemy.ext.proxy as proxy
+    import cPickle as pickle
+    import os
+    filename = os.path.join(os.path.dirname(self.file), 'compiled_docstrings.pickle')
+    data = pickle.load(file(filename))
 </%init>
 
+% for obj in data:
+<& pydoc.myt:obj_doc, obj=obj &>
+%
 
-<& pydoc.myt:obj_doc, obj=schema &>
-<& pydoc.myt:obj_doc, obj=engine, classes=[engine.SQLSession, engine.SQLEngine, engine.ResultProxy, engine.RowProxy] &>
-<& pydoc.myt:obj_doc, obj=sql, classes=[sql.ClauseParameters, sql.Compiled, sql.ClauseElement, sql.TableClause, sql.ColumnClause] &>
-<& pydoc.myt:obj_doc, obj=pool, classes=[pool.DBProxy, pool.Pool, pool.QueuePool, pool.SingletonThreadPool] &>
-<& pydoc.myt:obj_doc, obj=mapping, classes=[mapping.Mapper, mapping.MapperExtension] &>
-<& pydoc.myt:obj_doc, obj=mapping.query, classes=[mapping.query.Query] &>
-<& pydoc.myt:obj_doc, obj=mapping.objectstore, classes=[mapping.objectstore.Session, mapping.objectstore.Session.SessionTrans] &>
-<& pydoc.myt:obj_doc, obj=exceptions &>
-<& pydoc.myt:obj_doc, obj=proxy &>
-
-</&>
+</&>
\ No newline at end of file
index 7a1fca478198f8bab8751ea7048058a4ca4d46e4..2a274b03aba484476c1d5ea5a6417673521a11d1 100644 (file)
@@ -4,6 +4,9 @@ import sys,re,os
 print "Running txt2myt.py..."
 execfile("txt2myt.py")
 
+print "Generating docstring data"
+execfile("compile_docstrings.py")
+
 component_root = [
     {'components': './components'},
     {'content' : './content'}
@@ -11,7 +14,7 @@ component_root = [
 doccomp = ['document_base.myt']
 output = os.path.dirname(os.getcwd())
 
-sys.path = ['../../lib', './lib/'] + sys.path
+sys.path = ['./lib/'] + sys.path
 
 import documentgen
 
diff --git a/doc/build/lib/docstring.py b/doc/build/lib/docstring.py
new file mode 100644 (file)
index 0000000..0855cf1
--- /dev/null
@@ -0,0 +1,119 @@
+import re, types, string, inspect
+
+"""sucks a module and its contents into a simple documentation object, suitable for pickling"""
+
+class ObjectDoc(object):
+    def __init__(self, obj, functions=None, classes=None):
+        self.isclass = isinstance(obj, types.ClassType) or isinstance(obj, types.TypeType)
+        self.name= obj.__name__
+        functions = functions
+        classes= classes
+        
+        if not self.isclass:
+            if hasattr(obj, '__all__'):
+                objects = obj.__all__
+                sort = True
+            else:
+                objects = obj.__dict__.keys()
+                sort = True
+            if functions is None:
+                functions = [getattr(obj, x, None) 
+                    for x in objects 
+                    if getattr(obj,x,None) is not None and 
+                        (isinstance(getattr(obj,x), types.FunctionType))
+                        and not getattr(obj,x).__name__[0] == '_'
+                    ]
+                if sort:
+                    functions.sort(lambda a, b: cmp(a.__name__, b.__name__))
+            if classes is None:
+                classes = [getattr(obj, x, None) for x in objects 
+                    if getattr(obj,x,None) is not None and 
+                        (isinstance(getattr(obj,x), types.TypeType) 
+                        or isinstance(getattr(obj,x), types.ClassType))
+                        and not getattr(obj,x).__name__[0] == '_'
+                    ]
+                if sort:
+                    classes.sort(lambda a, b: cmp(a.__name__, b.__name__))
+        else:
+            if functions is None:
+                functions = (
+                    [getattr(obj, x).im_func for x in obj.__dict__.keys() if isinstance(getattr(obj,x), types.MethodType) 
+                    and 
+                    (getattr(obj, x).__name__ == '__init__' or not getattr(obj,x).__name__[0] == '_')
+                    ] + 
+                    [(x, getattr(obj, x)) for x in obj.__dict__.keys() if isinstance(getattr(obj,x), property) 
+                    and 
+                    not x[0] == '_'
+                    ]
+                 )
+                functions.sort(lambda a, b: cmp(getattr(a, '__name__', None) or a[0], getattr(b, '__name__', None) or b[0] ))
+            if classes is None:
+                classes = []
+        
+        if self.isclass:
+            self.description = "Class " + self.name
+            if hasattr(obj, '__mro__'):
+                l = []
+                mro = list(obj.__mro__[1:])
+                mro.reverse()
+                for x in mro:
+                    for y in x.__mro__[1:]:
+                        if y in l:
+                            del l[l.index(y)]
+                    l.insert(0, x)
+                self.description += "(" + string.join([x.__name__ for x in l], ',') + ")"
+        else:
+            self.description = "Module " + self.name
+
+        self.doc = obj.__doc__
+
+        self.functions = []
+        if not self.isclass and len(functions):
+            for func in functions:
+                self.functions.append(FunctionDoc(func))
+        else:
+            if len(functions):
+                for func in functions:
+                    if isinstance(func, types.FunctionType):
+                        self.functions.append(FunctionDoc(func))
+                    elif isinstance(func, tuple):
+                        self.functions.append(PropertyDoc(func[0], func[1]))
+                        
+        self.classes = []
+        for class_ in classes:
+            self.classes.append(ObjectDoc(class_))
+
+    def accept_visitor(self, visitor):
+        visitor.visit_object(self)
+
+class FunctionDoc(object):
+    def __init__(self, func):
+        argspec = inspect.getargspec(func)
+        argnames = argspec[0]
+        varargs = argspec[1]
+        varkw = argspec[2]
+        defaults = argspec[3] or ()
+        argstrings = []
+        for i in range(0, len(argnames)):
+            if i >= len(argnames) - len(defaults):
+                argstrings.append("%s=%s" % (argnames[i], repr(defaults[i - (len(argnames) - len(defaults))])))
+            else:
+                argstrings.append(argnames[i])
+        if varargs is not None:
+           argstrings.append("*%s" % varargs)
+        if varkw is not None:
+           argstrings.append("**%s" % varkw)
+        self.argstrings = self.arglist = argstrings
+        self.name = "def " + func.__name__
+        self.link = func.__name__
+        self.doc = func.__doc__
+    def accept_visitor(self, visitor):
+        visitor.visit_function(self)
+
+class PropertyDoc(object):
+    def __init__(self, name, prop):
+        self.doc = prop.__doc__
+        self.name = name + " = property()"
+        self.link = name
+    def accept_visitor(self, visitor):
+        visitor.visit_property(self)
index 1bff4896483334b9ebf1b311be000abfcde806f1..591e3b7f7a143fa7d5835b84855a027c29673098 100755 (executable)
@@ -4,6 +4,9 @@ import sys,re,os
 print "Running txt2myt.py..."\r
 execfile("txt2myt.py")\r
 \r
+print "Generating docstring data"\r
+execfile("compile_docstrings.py")\r
+\r
 component_root = [\r
     {'components': './components'},\r
     {'content' : './content'}\r
@@ -11,7 +14,7 @@ component_root = [
 doccomp = ['document_base.myt']\r
 output = os.path.dirname(os.getcwd())\r
 \r
-sys.path = ['../../lib', './lib/'] + sys.path\r
+sys.path = ['./lib/'] + sys.path\r
 \r
 import myghty.http.HTTPServerHandler as HTTPServerHandler\r
 \r