[Sqlalchemy-commits] [1444] sqlalchemy/branches/schema/doc/build: docstring gen is compiled to a dat
Brought to you by:
zzzeek
Menu
▾
▴
[Sqlalchemy-commits] [1444] sqlalchemy/branches/schema/doc/build: docstring gen is compiled to a datafile first, then presented.
|
From: <co...@sq...> - 2006-05-12 19:16:55
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head><style type="text/css"><!-- #msg dl { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; } #msg dt { float: left; width: 6em; font-weight: bold; } #msg dt:after { content:':';} #msg dl, #msg dt, #msg ul, #msg li { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; } #msg dl a { font-weight: bold} #msg dl a:link { color:#fc3; } #msg dl a:active { color:#ff0; } #msg dl a:visited { color:#cc6; } h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; } #msg pre { overflow: auto; background: #ffc; border: 1px #fc0 solid; padding: 6px; } #msg ul, pre { overflow: auto; } #patch { width: 100%; } #patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;} #patch .propset h4, #patch .binary h4 {margin:0;} #patch pre {padding:0;line-height:1.2em;margin:0;} #patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;} #patch .propset .diff, #patch .binary .diff {padding:10px 0;} #patch span {display:block;padding:0 10px;} #patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;} #patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;} #patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;} #patch .lines, .info {color:#888;background:#fff;} --></style> <title>[1444] sqlalchemy/branches/schema/doc/build: docstring gen is compiled to a datafile first, then presented.</title> </head> <body> <div id="msg"> <dl> <dt>Revision</dt> <dd>1444</dd> <dt>Author</dt> <dd>zzzeek</dd> <dt>Date</dt> <dd>2006-05-12 14:16:25 -0500 (Fri, 12 May 2006)</dd> </dl> <h3>Log Message</h3> <pre>docstring gen is compiled to a datafile first, then presented. decouples the need to have the documented library in the sys.path when running myghty formatting</pre> <h3>Modified Paths</h3> <ul> <li><a href="#sqlalchemybranchesschemadocbuildcomponentspydocmyt">sqlalchemy/branches/schema/doc/build/components/pydoc.myt</a></li> <li><a href="#sqlalchemybranchesschemadocbuildcontentdocstringsmyt">sqlalchemy/branches/schema/doc/build/content/docstrings.myt</a></li> <li><a href="#sqlalchemybranchesschemadocbuildgenhtmlpy">sqlalchemy/branches/schema/doc/build/genhtml.py</a></li> <li><a href="#sqlalchemybranchesschemadocbuildrunhtmlpy">sqlalchemy/branches/schema/doc/build/runhtml.py</a></li> </ul> <h3>Added Paths</h3> <ul> <li><a href="#sqlalchemybranchesschemadocbuildcompile_docstringspy">sqlalchemy/branches/schema/doc/build/compile_docstrings.py</a></li> <li><a href="#sqlalchemybranchesschemadocbuildlibdocstringpy">sqlalchemy/branches/schema/doc/build/lib/docstring.py</a></li> </ul> </div> <div id="patch"> <h3>Diff</h3> <a id="sqlalchemybranchesschemadocbuildcompile_docstringspy"></a> <div class="addfile"><h4>Added: sqlalchemy/branches/schema/doc/build/compile_docstrings.py (1443 => 1444)</h4> <pre class="diff"><span> <span class="info">--- sqlalchemy/branches/schema/doc/build/compile_docstrings.py 2006-05-12 17:13:17 UTC (rev 1443) +++ sqlalchemy/branches/schema/doc/build/compile_docstrings.py 2006-05-12 19:16:25 UTC (rev 1444) </span><span class="lines">@@ -0,0 +1,36 @@ </span><ins>+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.engine.strategies as strategies +import sqlalchemy.sql as sql +import sqlalchemy.pool as pool +import sqlalchemy.orm as orm +import sqlalchemy.exceptions as exceptions +import sqlalchemy.ext.proxy as proxy +import sqlalchemy.mods.threadlocal as threadlocal + +objects = [] +def make_doc(obj, classes=None, functions=None): + objects.append(docstring.ObjectDoc(obj, classes=classes, functions=functions)) + +make_doc(obj=sql, classes=[sql.Engine, sql.AbstractDialect, sql.ClauseParameters, sql.Compiled, sql.ClauseElement, sql.TableClause, sql.ColumnClause]) +make_doc(obj=schema) +make_doc(obj=engine, classes=[engine.ComposedSQLEngine, engine.Connection, engine.Transaction, engine.Dialect, engine.ConnectionProvider, engine.ExecutionContext, engine.ResultProxy, engine.RowProxy]) +make_doc(obj=strategies) +make_doc(obj=orm, classes=[orm.Mapper, orm.MapperExtension]) +make_doc(obj=orm.query, classes=[orm.query.Query]) +make_doc(obj=orm.session, classes=[orm.session.Session, orm.session.SessionTransaction]) +make_doc(obj=threadlocal) +make_doc(obj=exceptions) +make_doc(obj=pool, classes=[pool.DBProxy, pool.Pool, pool.QueuePool, pool.SingletonThreadPool]) +make_doc(obj=proxy) + + +output = os.path.join(os.getcwd(), 'content', "compiled_docstrings.pickle") +pickle.dump(objects, file(output, 'w')) </ins><span class="cx">\ No newline at end of file </span></span></pre></div> <a id="sqlalchemybranchesschemadocbuildcomponentspydocmyt"></a> <div class="modfile"><h4>Modified: sqlalchemy/branches/schema/doc/build/components/pydoc.myt (1443 => 1444)</h4> <pre class="diff"><span> <span class="info">--- sqlalchemy/branches/schema/doc/build/components/pydoc.myt 2006-05-12 17:13:17 UTC (rev 1443) +++ sqlalchemy/branches/schema/doc/build/components/pydoc.myt 2006-05-12 19:16:25 UTC (rev 1444) </span><span class="lines">@@ -1,5 +1,5 @@ </span><span class="cx"> <%global> </span><del>- import re, types, string </del><ins>+ import re, types, string, docstring </ins><span class="cx"> def format_paragraphs(text): </span><span class="cx"> return re.sub(r'([\w])\n([\w])', r'\1 \2', text or '', re.S) </span><span class="cx"> </%global> </span><span class="lines">@@ -7,142 +7,57 @@ </span><span class="cx"> <%method obj_doc> </span><span class="cx"> <%args> </span><span class="cx"> obj </span><del>- functions = None - classes = None </del><span class="cx"> </%args> </span><del>- <%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__'): - 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) - description += "(" + string.join([x.__name__ for x in l], ',') + ")" - else: - description = "Module " + name - </%init> </del><ins>+ +<&|doclib.myt:item, name=obj.name, description=obj.description &> +<&|formatting.myt:formatplain&><% format_paragraphs(obj.doc) %></&> </ins><span class="cx"> </span><del>-<&|doclib.myt:item, name=obj.__name__, description=description &> -<&|formatting.myt:formatplain&><% format_paragraphs(obj.__doc__) %></&> - -% if not isclass and len(functions): </del><ins>+% if not obj.isclass and obj.functions: </ins><span class="cx"> <&|doclib.myt:item, name="modfunc", description="Module Functions" &> </span><span class="cx"> <&|formatting.myt:paramtable&> </span><del>-% for func in functions: </del><ins>+% for func in obj.functions: </ins><span class="cx"> <& SELF:function_doc, func=func &> </span><span class="cx"> % </span><span class="cx"> </&> </span><span class="cx"> </&> </span><span class="cx"> % else: </span><del>-% if len(functions): </del><ins>+% if obj.functions: </ins><span class="cx"> <&|formatting.myt:paramtable&> </span><del>-% for func in functions: -% if isinstance(func, types.FunctionType): </del><ins>+% for func in obj.functions: +% if isinstance(func, docstring.FunctionDoc): </ins><span class="cx"> <& SELF:function_doc, func=func &> </span><del>-% elif isinstance(func, tuple): - <& SELF:property_doc, name = func[0], prop=func[1] &> </del><ins>+% elif isinstance(func, docstring.PropertyDoc): + <& SELF:property_doc, prop=func &> </ins><span class="cx"> % </span><span class="cx"> % </span><span class="cx"> </&> </span><span class="cx"> % </span><span class="cx"> % </span><span class="cx"> </span><del>-% if len(classes): </del><ins>+% if obj.classes: </ins><span class="cx"> <&|formatting.myt:paramtable&> </span><del>-% for class_ in classes: </del><ins>+% for class_ in obj.classes: </ins><span class="cx"> <& SELF:obj_doc, obj=class_ &> </span><span class="cx"> % </span><span class="cx"> </&> </span><span class="cx"> % </span><span class="cx"> </&> </span><span class="cx"> </span><del>- </del><span class="cx"> </%method> </span><span class="cx"> </span><span class="cx"> <%method function_doc> </span><span class="cx"> <%args>func</%args> </span><del>- <%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__) %></&> </del><ins>+ <&|formatting.myt:function_doc, name=func.name, link=func.link, arglist=func.arglist &> + <&|formatting.myt:formatplain&><% format_paragraphs(func.doc) %></&> </ins><span class="cx"> </&> </span><span class="cx"> </%method> </span><span class="cx"> </span><span class="cx"> </span><span class="cx"> <%method property_doc> </span><span class="cx"> <%args> </span><del>- name </del><span class="cx"> prop </span><span class="cx"> </%args> </span><del>- <&|formatting.myt:member_doc, name=name + " = property()", link=name &> - <&|formatting.myt:formatplain&><% format_paragraphs(prop.__doc__) %></&> </del><ins>+ <&|formatting.myt:member_doc, name=prop.name, link=prop.link &> + <&|formatting.myt:formatplain&><% format_paragraphs(prop.doc) %></&> </ins><span class="cx"> </&> </span><span class="cx"> </%method> </span><span class="cx">\ No newline at end of file </span></span></pre></div> <a id="sqlalchemybranchesschemadocbuildcontentdocstringsmyt"></a> <div class="modfile"><h4>Modified: sqlalchemy/branches/schema/doc/build/content/docstrings.myt (1443 => 1444)</h4> <pre class="diff"><span> <span class="info">--- sqlalchemy/branches/schema/doc/build/content/docstrings.myt 2006-05-12 17:13:17 UTC (rev 1443) +++ sqlalchemy/branches/schema/doc/build/content/docstrings.myt 2006-05-12 19:16:25 UTC (rev 1444) </span><span class="lines">@@ -2,28 +2,14 @@ </span><span class="cx"> <%attr>title='Modules and Classes'</%attr> </span><span class="cx"> <&|doclib.myt:item, name="docstrings", description="Modules and Classes" &> </span><span class="cx"> <%init> </span><del>- import sqlalchemy.schema as schema - import sqlalchemy.engine as engine - import sqlalchemy.engine.strategies as strategies - import sqlalchemy.sql as sql - import sqlalchemy.pool as pool - import sqlalchemy.orm as orm - import sqlalchemy.exceptions as exceptions - import sqlalchemy.ext.proxy as proxy - import sqlalchemy.mods.threadlocal as threadlocal </del><ins>+ import cPickle as pickle + import os + filename = os.path.join(os.path.dirname(self.file), 'compiled_docstrings.pickle') + data = pickle.load(file(filename)) </ins><span class="cx"> </%init> </span><span class="cx"> </span><ins>+% for obj in data: +<& pydoc.myt:obj_doc, obj=obj &> +% </ins><span class="cx"> </span><del>-<& pydoc.myt:obj_doc, obj=sql, classes=[sql.Engine, sql.AbstractDialect, sql.ClauseParameters, sql.Compiled, sql.ClauseElement, sql.TableClause, sql.ColumnClause] &> -<& pydoc.myt:obj_doc, obj=schema &> -<& pydoc.myt:obj_doc, obj=engine, classes=[engine.ComposedSQLEngine, engine.Connection, engine.Transaction, engine.Dialect, engine.ConnectionProvider, engine.ExecutionContext, engine.ResultProxy, engine.RowProxy] &> -<& pydoc.myt:obj_doc, obj=strategies &> -<& pydoc.myt:obj_doc, obj=orm, classes=[orm.Mapper, orm.MapperExtension] &> -<& pydoc.myt:obj_doc, obj=orm.query, classes=[orm.query.Query] &> -<& pydoc.myt:obj_doc, obj=orm.session, classes=[orm.session.Session, orm.session.SessionTransaction] &> -<& pydoc.myt:obj_doc, obj=threadlocal &> -<& pydoc.myt:obj_doc, obj=exceptions &> -<& pydoc.myt:obj_doc, obj=pool, classes=[pool.DBProxy, pool.Pool, pool.QueuePool, pool.SingletonThreadPool] &> -<& pydoc.myt:obj_doc, obj=proxy &> - -</&> </del><ins>+</&> </ins><span class="cx">\ No newline at end of file </span></span></pre></div> <a id="sqlalchemybranchesschemadocbuildgenhtmlpy"></a> <div class="modfile"><h4>Modified: sqlalchemy/branches/schema/doc/build/genhtml.py (1443 => 1444)</h4> <pre class="diff"><span> <span class="info">--- sqlalchemy/branches/schema/doc/build/genhtml.py 2006-05-12 17:13:17 UTC (rev 1443) +++ sqlalchemy/branches/schema/doc/build/genhtml.py 2006-05-12 19:16:25 UTC (rev 1444) </span><span class="lines">@@ -4,6 +4,9 @@ </span><span class="cx"> print "Running txt2myt.py..." </span><span class="cx"> execfile("txt2myt.py") </span><span class="cx"> </span><ins>+print "Generating docstring data" +execfile("compile_docstrings.py") + </ins><span class="cx"> component_root = [ </span><span class="cx"> {'components': './components'}, </span><span class="cx"> {'content' : './content'} </span><span class="lines">@@ -11,7 +14,7 @@ </span><span class="cx"> doccomp = ['document_base.myt'] </span><span class="cx"> output = os.path.dirname(os.getcwd()) </span><span class="cx"> </span><del>-sys.path = ['../../lib', './lib/'] + sys.path </del><ins>+sys.path = ['./lib/'] + sys.path </ins><span class="cx"> </span><span class="cx"> import documentgen </span><span class="cx"> </span></span></pre></div> <a id="sqlalchemybranchesschemadocbuildlibdocstringpy"></a> <div class="addfile"><h4>Added: sqlalchemy/branches/schema/doc/build/lib/docstring.py (1443 => 1444)</h4> <pre class="diff"><span> <span class="info">--- sqlalchemy/branches/schema/doc/build/lib/docstring.py 2006-05-12 17:13:17 UTC (rev 1443) +++ sqlalchemy/branches/schema/doc/build/lib/docstring.py 2006-05-12 19:16:25 UTC (rev 1444) </span><span class="lines">@@ -0,0 +1,119 @@ </span><ins>+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) </ins></span></pre></div> <a id="sqlalchemybranchesschemadocbuildrunhtmlpy"></a> <div class="modfile"><h4>Modified: sqlalchemy/branches/schema/doc/build/runhtml.py (1443 => 1444)</h4> <pre class="diff"><span> <span class="info">--- sqlalchemy/branches/schema/doc/build/runhtml.py 2006-05-12 17:13:17 UTC (rev 1443) +++ sqlalchemy/branches/schema/doc/build/runhtml.py 2006-05-12 19:16:25 UTC (rev 1444) </span><span class="lines">@@ -4,6 +4,9 @@ </span><span class="cx"> print "Running txt2myt.py..." </span><span class="cx"> execfile("txt2myt.py") </span><span class="cx"> </span><ins>+print "Generating docstring data" +execfile("compile_docstrings.py") + </ins><span class="cx"> component_root = [ </span><span class="cx"> {'components': './components'}, </span><span class="cx"> {'content' : './content'} </span><span class="lines">@@ -11,7 +14,7 @@ </span><span class="cx"> doccomp = ['document_base.myt'] </span><span class="cx"> output = os.path.dirname(os.getcwd()) </span><span class="cx"> </span><del>-sys.path = ['../../lib', './lib/'] + sys.path </del><ins>+sys.path = ['./lib/'] + sys.path </ins><span class="cx"> </span><span class="cx"> import myghty.http.HTTPServerHandler as HTTPServerHandler </span><span class="cx"> </span></span></pre> </div> </div> </body> </html> |
