From 23d1698acc52a59b801de81c4e10e75fca19fdf4 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Mon, 30 Jul 2007 05:31:40 +0000 Subject: [PATCH] doc reorganize; greater emphasis on overview (just like with 0.1), but still with tutorials (TODO). --- doc/build/content/datamapping.txt | 4 +++- doc/build/content/dbengine.txt | 1 + doc/build/content/sqlconstruction.txt | 10 ++-------- doc/build/content/threadlocal.txt | 2 -- doc/build/genhtml.py | 10 +++++----- doc/build/read_markdown.py | 6 +++--- doc/build/templates/formatting.html | 18 +++++++++++------- doc/build/templates/nav.html | 3 +++ 8 files changed, 28 insertions(+), 26 deletions(-) delete mode 100644 doc/build/content/threadlocal.txt diff --git a/doc/build/content/datamapping.txt b/doc/build/content/datamapping.txt index d35fecfb34..02390aafad 100644 --- a/doc/build/content/datamapping.txt +++ b/doc/build/content/datamapping.txt @@ -1,9 +1,11 @@ [alpha_api]: javascript:alphaApi() [alpha_implementation]: javascript:alphaImplementation() -Data Mapping {@name=datamapping} +Object Relational Tutorial {@name=datamapping} ============ +**TUTORIAL FORMAT IS TODO** + ### Basic Data Mapping {@name=datamapping} Data mapping describes the process of defining `Mapper` objects, which associate table metadata with user-defined classes. diff --git a/doc/build/content/dbengine.txt b/doc/build/content/dbengine.txt index c03d569374..c88a6cd6ba 100644 --- a/doc/build/content/dbengine.txt +++ b/doc/build/content/dbengine.txt @@ -5,6 +5,7 @@ The **Engine** is the starting point for any SQLAlchemy application. It's "home The general structure is this: + {diagram} +-----------+ __________ /---| Pool |---\ (__________) +-------------+ / +-----------+ \ +--------+ | | diff --git a/doc/build/content/sqlconstruction.txt b/doc/build/content/sqlconstruction.txt index a672fb5cec..5adc00a99e 100644 --- a/doc/build/content/sqlconstruction.txt +++ b/doc/build/content/sqlconstruction.txt @@ -1,13 +1,7 @@ -Constructing SQL Queries via Python Expressions {@name=sql} +SQL Expression Language Tutorial {@name=sql} =============================================== -*Note:* This section describes how to use SQLAlchemy to construct SQL queries and receive result sets. It does *not* cover the object relational mapping capabilities of SQLAlchemy; that is covered later on in [datamapping](rel:datamapping). However, both areas of functionality work similarly in how selection criterion is constructed, so if you are interested just in ORM, you should probably skim through basic [sql_whereclause](rel:sql_whereclause) construction before moving on. - -Once you have used the `sqlalchemy.schema` module to construct your tables and/or reflect them from the database, performing SQL queries using those table meta data objects is done via the `sqlalchemy.sql` package. This package defines a large set of classes, each of which represents a particular kind of lexical construct within a SQL query; all are descendants of the common base class `sqlalchemy.sql.ClauseElement`. A full query is represented via a structure of `ClauseElement`s. A set of reasonably intuitive creation functions is provided by the `sqlalchemy.sql` package to create these structures; these functions are described in the rest of this section. - -Executing a `ClauseElement` structure can be performed in two general ways. You can use an `Engine` or a `Connection` object's `execute()` method to which you pass the query structure; this is known as **explicit style**. Or, if the `ClauseElement` structure is built upon Table metadata which is bound to an `Engine` directly, you can simply call `execute()` on the structure itself, known as **implicit style**. In both cases, the execution returns a cursor-like object (more on that later). The same clause structure can be executed repeatedly. The `ClauseElement` is compiled into a string representation by an underlying `Compiler` object which is associated with the `Engine` via its `Dialect`. - -The examples below all include a dump of the generated SQL corresponding to the query object, as well as a dump of the statement's bind parameters. In all cases, bind parameters are shown as named parameters using the colon format (i.e. ':name'). When the statement is compiled into a database-specific version, the named-parameter statement and its bind values are converted to the proper paramstyle for that database automatically. +**TUTORIAL FORMAT IS TODO** For this section, we will mostly use the implcit style of execution, meaning the `Table` objects are associated with a bound instance of `MetaData`, and constructed `ClauseElement` objects support self-execution. Assume the following configuration: diff --git a/doc/build/content/threadlocal.txt b/doc/build/content/threadlocal.txt deleted file mode 100644 index 20ad270aef..0000000000 --- a/doc/build/content/threadlocal.txt +++ /dev/null @@ -1,2 +0,0 @@ -The threadlocal mod {@name=threadlocal} -============ diff --git a/doc/build/genhtml.py b/doc/build/genhtml.py index ddc2e8a926..67e1c04421 100644 --- a/doc/build/genhtml.py +++ b/doc/build/genhtml.py @@ -14,13 +14,13 @@ import optparse files = [ 'index', 'documentation', - 'tutorial', - 'dbengine', - 'metadata', - 'sqlconstruction', + 'intro', 'datamapping', - 'unitofwork', 'adv_datamapping', + 'unitofwork', + 'sqlconstruction', + 'dbengine', + 'metadata', 'types', 'pooling', 'plugins', diff --git a/doc/build/read_markdown.py b/doc/build/read_markdown.py index c80589fc2b..0733142c4e 100644 --- a/doc/build/read_markdown.py +++ b/doc/build/read_markdown.py @@ -154,7 +154,7 @@ def replace_pre_with_mako(tree): sqlre2 = re.compile(r'{opensql}(.*?\n)((?:BEGIN|SELECT|INSERT|DELETE|UPDATE|CREATE|DROP).*?)\n\s*(\n|$)', re.S) text = sqlre2.sub(r"<%call expr='formatting.poppedcode()' >\1\n\2\n\n", text) - tag = et.Element("MAKO:formatting.code") + tag = et.Element("MAKO:formatting.code", extension='extension', paged='paged', toc='toc') if code: tag.attrib["syntaxtype"] = repr(code) if title: @@ -170,13 +170,13 @@ def replace_pre_with_mako(tree): parents = get_parent_map(tree) for precode in tree.findall('.//pre/code'): - reg = re.compile(r'\{(python|code)(?: title="(.*?)"){0,1}\}(.*)', re.S) + reg = re.compile(r'\{(python|code|diagram)(?: title="(.*?)"){0,1}\}(.*)', re.S) m = reg.match(precode[0].text.lstrip()) if m: code = m.group(1) title = m.group(2) text = m.group(3) - text = re.sub(r'{(python|code).*?}(\n\s*)?', '', text) + text = re.sub(r'{(python|code|diagram).*?}(\n\s*)?', '', text) splice_code_tag(parents[precode], text, code=code, title=title) elif precode.text.lstrip().startswith('>>> '): splice_code_tag(parents[precode], precode.text) diff --git a/doc/build/templates/formatting.html b/doc/build/templates/formatting.html index 4068e3adfa..629ec87cca 100644 --- a/doc/build/templates/formatting.html +++ b/doc/build/templates/formatting.html @@ -55,7 +55,7 @@ ${ caller.body() } -<%def name="code(title=None, syntaxtype='mako', html_escape=False, use_sliders=False)"> +<%def name="code(toc, paged, extension, title=None, syntaxtype='mako', html_escape=False, use_sliders=False)"> <% def fix_indent(f): f =string.expandtabs(f, 4) @@ -76,15 +76,19 @@ return g.rstrip() - + p = re.compile(r'
(.*?)
', re.S) def hlight(match): return "
" + highlight.highlight(fix_indent(match.group(1)), html_escape = html_escape, syntaxtype = syntaxtype) + "
" - try: - content = p.sub(hlight, "
" + capture(caller.body) + "
") - except: - raise "the content is " + str(capture(caller.body)) - + + def link(match): + return capture(nav.toclink, toc, match.group(2), extension, paged, description=match.group(1)) + + content = re.sub(r'\[(.+?)\]\(rel:(.+?)\)', link, capture(caller.body)) + if syntaxtype != 'diagram': + content = p.sub(hlight, "
" + content + "
") + else: + content = "
" + content + "
" %>
diff --git a/doc/build/templates/nav.html b/doc/build/templates/nav.html index 38147d89de..2438303ff7 100644 --- a/doc/build/templates/nav.html +++ b/doc/build/templates/nav.html @@ -22,6 +22,9 @@ % if item: ${ description } % else: + <% + #raise Exception("Can't find TOC link for '%s'" % path) + %> ${ description } % endif -- 2.47.3