From 229d2ee4e9e189feb25578c07c850606178d5b76 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Sat, 17 Mar 2007 16:49:45 +0000 Subject: [PATCH] integrated docutils formatting into generated documentation; restructuredtext fixes throughout docstrings --- doc/build/content/docstrings.html | 6 + doc/build/gen_docstrings.py | 4 +- doc/build/templates/base.html | 2 +- doc/build/templates/pydoc.html | 21 ++- doc/build/templates/toc.html | 7 +- doc/docutil.css | 274 ++++++++++++++++++++++++++++ lib/sqlalchemy/engine/base.py | 2 +- lib/sqlalchemy/ext/selectresults.py | 9 +- lib/sqlalchemy/orm/__init__.py | 2 +- lib/sqlalchemy/orm/mapper.py | 23 ++- lib/sqlalchemy/orm/query.py | 47 ++--- lib/sqlalchemy/orm/session.py | 35 ++-- lib/sqlalchemy/schema.py | 24 +-- lib/sqlalchemy/sql.py | 30 +-- 14 files changed, 397 insertions(+), 89 deletions(-) create mode 100644 doc/docutil.css diff --git a/doc/build/content/docstrings.html b/doc/build/content/docstrings.html index e8b480f29b..709b99abd0 100644 --- a/doc/build/content/docstrings.html +++ b/doc/build/content/docstrings.html @@ -5,6 +5,12 @@ <%namespace name="nav" file="nav.html"/> <%namespace name="pydoc" file="pydoc.html"/> <%def name="title()">SQLAlchemy 0.3 Documentation - Modules and Classes + +<%def name="style()"> + ${parent.style()} + + + <%! filename = 'docstrings' %> diff --git a/doc/build/gen_docstrings.py b/doc/build/gen_docstrings.py index 2cef463d4e..0360ef96fa 100644 --- a/doc/build/gen_docstrings.py +++ b/doc/build/gen_docstrings.py @@ -29,8 +29,8 @@ def make_all_docs(): make_doc(obj=types), make_doc(obj=engine), make_doc(obj=engine.url), - make_doc(obj=orm, classes=[orm.MapperExtension]), - make_doc(obj=orm.mapperlib, classes=[orm.mapperlib.Mapper]), + make_doc(obj=orm), + make_doc(obj=orm.mapperlib, classes=[orm.mapperlib.MapperExtension, orm.mapperlib.Mapper]), make_doc(obj=orm.query, classes=[orm.query.Query, orm.query.QueryContext, orm.query.SelectionContext]), make_doc(obj=orm.session, classes=[orm.session.Session, orm.session.SessionTransaction]), make_doc(obj=pool), diff --git a/doc/build/templates/base.html b/doc/build/templates/base.html index 76a2d8a45b..a0b52be1bf 100644 --- a/doc/build/templates/base.html +++ b/doc/build/templates/base.html @@ -2,7 +2,7 @@ from mako.ext.autohandler import autohandler %> <%inherit file="${autohandler(template, context)}"/> -<%page cached="False" cache_key="${self.filename}"/> +<%page cached="True" cache_key="${self.filename}"/> <%doc> base.html - common to all documentation pages. intentionally separate diff --git a/doc/build/templates/pydoc.html b/doc/build/templates/pydoc.html index 72e31e0d99..9c5d730b37 100644 --- a/doc/build/templates/pydoc.html +++ b/doc/build/templates/pydoc.html @@ -1,15 +1,16 @@ <%doc>pydoc.myt - provides formatting functions for printing docstring.AbstractDoc generated python documentation objects. <%! import docstring -import sys, re +from docutils.core import publish_parts +import re, sys -def whitespace(docstring): - if not docstring: +def whitespace(content): + """trim left whitespace.""" + if not content: return '' - # Convert tabs to spaces (following the normal Python rules) # and split into a list of lines: - lines = docstring.expandtabs().splitlines() + lines = content.expandtabs().splitlines() # Determine minimum indentation (first line doesn't count): indent = sys.maxint for line in lines[1:]: @@ -29,8 +30,8 @@ def whitespace(docstring): # Return a single string: return '\n'.join(trimmed) -def convquotes(text): - return re.sub(r'``(.*?)``', lambda m: "%s" % m.group(1), text) +def formatdocstring(content): + return publish_parts(whitespace(content), writer_name='html')['body'] %> <%namespace name="formatting" file="formatting.html"/> @@ -53,7 +54,7 @@ def convquotes(text): <%call expr="formatting.section(toc=toc, path=obj.toc_path, description=htmldescription, paged=paged, extension=extension)"> % if obj.doc: - 
${obj.doc or '' |whitespace, h,convquotes}
+
${obj.doc or '' |formatdocstring}
% endif % if not obj.isclass and obj.functions: @@ -96,7 +97,7 @@ def convquotes(text): def ${func.name}(${", ".join(map(lambda k: "%s" % k, func.arglist))})
- 
${func.doc or '' | whitespace, h, convquotes}
+ ${func.doc or '' | formatdocstring}
@@ -106,7 +107,7 @@ def convquotes(text): ${prop.name} = property()
- 
${prop.doc or '' | whitespace, h, convquotes}
+ ${prop.doc or '' | formatdocstring}
diff --git a/doc/build/templates/toc.html b/doc/build/templates/toc.html index d164d867dd..f4ea353ec1 100644 --- a/doc/build/templates/toc.html +++ b/doc/build/templates/toc.html @@ -24,7 +24,12 @@ <%def name="printtoc(root, paged, extension, current=None, children=True, anchor_toplevel=False)">