From: Mike Bayer Date: Fri, 12 May 2006 19:25:41 +0000 (+0000) Subject: added pre-compiled docstring support X-Git-Tag: rel_0_2_0~31 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=71fcffb2a27c5c4192bbd960eba91993f7a21b66;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git added pre-compiled docstring support --- diff --git a/doc/build/compile_docstrings.py b/doc/build/compile_docstrings.py new file mode 100644 index 0000000000..fb95273190 --- /dev/null +++ b/doc/build/compile_docstrings.py @@ -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 diff --git a/doc/build/components/pydoc.myt b/doc/build/components/pydoc.myt index 442403513a..989ea2199c 100644 --- a/doc/build/components/pydoc.myt +++ b/doc/build/components/pydoc.myt @@ -1,140 +1,63 @@ <%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) <%method obj_doc> <%args> obj - functions = None - classes = None - <%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 - - -<&|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 function_doc> <%args>func - <%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) - - - <&|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 property_doc> <%args> - name prop - <&|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) %> \ No newline at end of file diff --git a/doc/build/content/docstrings.myt b/doc/build/content/docstrings.myt index 1e157b6aae..a30a5fb636 100644 --- a/doc/build/content/docstrings.myt +++ b/doc/build/content/docstrings.myt @@ -2,24 +2,14 @@ <%attr>title='Modules and Classes' <&|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)) +% 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 diff --git a/doc/build/genhtml.py b/doc/build/genhtml.py index 7a1fca4781..2a274b03ab 100644 --- a/doc/build/genhtml.py +++ b/doc/build/genhtml.py @@ -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 index 0000000000..0855cf1387 --- /dev/null +++ b/doc/build/lib/docstring.py @@ -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) diff --git a/doc/build/runhtml.py b/doc/build/runhtml.py index 1bff489648..591e3b7f7a 100755 --- a/doc/build/runhtml.py +++ b/doc/build/runhtml.py @@ -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 myghty.http.HTTPServerHandler as HTTPServerHandler