upgrade docs to newer format from SQLA

4 files changed, 426 insertions, 230 deletions

diff --git a/doc/build/static/docs.css b/doc/build/static/docs.css
index d40dad0..bf67641 100644
--- a/doc/build/static/docs.css
+++ b/doc/build/static/docs.css
@@ -1,225 +1,329 @@
-/* documentation section styles */
+/* global */
 
-body, td {
-	font-family: Tahoma,Geneva,sans-serif;
+body {
+  background-color: #FDFBFC;
+  margin:38px;
+  color:#333333;
 }
 
-body {
-	background-color: #FDFBFC;
-	margin:38px;
-	color:#333333;
+a {
+    font-weight:normal; 
+    text-decoration:none;
 }
 
 form {
     display:inline;
 }
 
-p {
-	margin-top:10px;
-	margin-bottom:10px;
+/* hyperlinks */
+
+a:link, a:visited, a:active {
+    color:#0000FF;
+}
+a:hover {
+    color:#700000;
+    text-decoration:underline;
 }
 
+/* paragraph links after sections.
+   These aren't visible until hovering
+   over the <h> tag, then have a 
+   "reverse video" effect over the actual
+   link
+ */
 
-a {
-        font-weight:normal; 
-        text-decoration:none;
+a.headerlink {
+    font-size: 0.8em;
+    padding: 0 4px 0 4px;
+    text-decoration: none;
+    visibility: hidden;
 }
-a:link {color:#0000FF;}
-a:visited {color:#0000FF;}
-a:active {color:#0000FF;}
-a:hover {color:#700000;}
 
+h1:hover > a.headerlink,
+h2:hover > a.headerlink,
+h3:hover > a.headerlink,
+h4:hover > a.headerlink,
+h5:hover > a.headerlink,
+h6:hover > a.headerlink,
+dt:hover > a.headerlink {
+    visibility: visible;
+}
 
-strong a {
-    font-weight: bold;
+a.headerlink:hover {
+    background-color: #990000;
+    color: white;
 }
 
-#search {
-    float:right;
+
+/* Container setup */
+
+#docs-container {
+  max-width:1000px;
 }
 
-#searchform {
-    padding:20px;
+
+/* header/footer elements */
+
+#docs-header h1 {
+    font-size:20px;
+    color: #222222;
+    margin: 0;
+    padding: 0;
 }
 
-#pagecontrol {
-    float:right;
+#docs-header {
+  font-family:Tahoma, Geneva,sans-serif;
+
+  font-size:.9em;
+
 }
 
-.topnav {
-	background-color: #eeeeee;
-	border: solid 1px #ccc;
-	padding:10px;
-	margin:10px 0px 10px 0px;
+#docs-top-navigation,
+#docs-bottom-navigation {
+  font-family: Tahoma, Geneva, sans-serif;
+  background-color: #EEE;
+  border: solid 1px #CCC;
+  padding:10px;
+  font-size:.9em;
 }
 
-.bottomnav {
-	background-color: #eeeeee;
-    border:1px solid #CCCCCC;
+#docs-top-navigation {
+  margin:10px 0px 10px 0px;
+  line-height:1.2em;
+}
+
+.docs-navigation-links {
+  font-family:Tahoma, Geneva,sans-serif;
+}
+
+#docs-bottom-navigation {
     float:right;
     margin: 1em 0 1em 5px;
-    padding:10px;
 }
 
-.document {
-	border: solid 1px #ccc;
+#docs-copyright {
+    font-size:.85em;
+    padding:5px 0px;
 }
 
-.topnav .prevnext {
-    padding: 5px 0px 0px 0px;
-    /*font-size: 0.8em*/
+#docs-header h1,
+#docs-top-navigation h1,
+#docs-top-navigation h2 {
+  font-family:Tahoma,Geneva,sans-serif;
+  font-weight:normal;
 }
 
-h1, h2, h3, h4, h5 {
-    font-weight:bold;
+#docs-top-navigation h2 {
+    margin:16px 4px 7px 5px;
+    font-size:2em;
 }
 
-h1 {
-    font-size:1.6em;
-    font-weight:bold;
-}
-.document h1, .document h2, .document h3, .document h4, .document h5 {
-    font-size: 1.2em;
+#docs-search {
+    float:right;
 }
 
-.document img {
-    display:block;
-    margin: 0 auto;
+#docs-top-page-control {
+  float:right;
+  width:350px;
 }
 
-.document h1 {
-    display:none;
+#docs-top-page-control ul {
+  padding:0;
+  margin:0;
 }
 
-.topnav h2 {
-    margin:26px 4px 0px 5px;
-    font-size:1.6em;
-    font-weight:normal;
-    line-height:1.6em; 
+#docs-top-page-control li {
+    list-style-type:none;
+    padding:1px 8px;
 }
 
-.topnav h3 {
+
+#docs-container .version-num {
     font-weight: bold;
-    font-size: 1.4em;
-    margin:0px;
-    display:inline;
 }
 
-.topnav li,
-li.toctree-l1,
-li.toctree-l1 li
-{
-    list-style-type:disc;
-    margin:0px;
-    padding:1px 8px;
+
+/* content container, sidebar */
+
+#docs-body-container {
+  background-color:#EFEFEF;
+  border: solid 1px #CCC;
+
 }
 
+#docs-body,
+#docs-sidebar
+ {
+  /*font-family: helvetica, arial, sans-serif;
+  font-size:.9em;*/
+
+  font-family: Tahoma, Geneva, sans-serif;
+  /*font-size:.85em;*/
+  line-height:1.5em;
 
-.topnav li ul, 
-li.toctree-l1 ul
-{
-    padding:0px 0px 0px 20px;
 }
 
-.topnav li ul li li, 
-li.toctree-l1 ul li li
-{
-    /*font-size:.90em;*/
+#docs-sidebar > ul {
+  font-size:.9em;
 }
 
-.sourcelink {
-    font-size:.8em;
-    text-align:right;
-    padding-top:10px;
+#docs-sidebar {
+  float:left;
+  width:212px;
+  padding: 10px 0 0 15px;
+  /*font-size:.85em;*/
 }
 
-.section {
-    line-height: 1.5em;
-    padding:8px 10px 20px 10px;
-    margin:10px 0px 0px;
+#docs-sidebar h3, #docs-sidebar h4 {
+    background-color: #DDDDDD;
+    color: #222222;
+    font-family: Tahoma, Geneva,sans-serif;
+    font-size: 1.1em;
+    font-weight: normal;
+    margin: 10px 0 0 -15px;
+    padding: 5px 10px 5px 10px;
+    text-shadow: 1px 1px 0 white;
+    width:210px;
 }
 
-.section .section {
-    margin:0px 0px 0px 0px;
-    padding: 0px;
+#docs-sidebar h3 a, #docs-sidebar h4 a {
+  color: #222222;
+}
+#docs-sidebar ul {
+  margin: 10px 10px 10px 0px;
+  padding: 0;
+  list-style: none outside none;
 }
 
-.section .section .section {
-    margin:0px 0px 0px 20px;
+
+#docs-sidebar ul ul {
+    margin-bottom: 0;
+    margin-top: 0;
+    list-style: square outside none;
+    margin-left: 20px;
 }
 
-.section .section .section .section {
-    margin:0px 0px 0px 20px;
+#docs-body {
+  background-color:#FFFFFF;
+  padding:1px 10px 10px 10px;
 }
 
-th.field-name {
-    text-align:right;
+#docs-body.withsidebar {
+  margin: 0 0 0 230px;
+  border-left:3px solid #DFDFDF;
 }
 
-div.note, div.warning, p.deprecated  {
-    background-color:#EEFFEF;
+#docs-body h1,
+#docs-body h2,
+#docs-body h3,
+#docs-body h4 {
+  font-family:Tahoma, Geneva, sans-serif;
 }
 
+#docs-body h1 {
+  /* hide the <h1> for each content section. */
+  display:none;
+  font-size:1.8em;
+}
 
-div.admonition, div.topic, p.deprecated {
-    border:1px solid #CCCCCC;
-    margin:5px 5px 5px 5px;
-    padding:5px 5px 5px 35px;
-    font-size:.9em;
+#docs-body h2 {
+  font-size:1.6em;
 }
 
-div.warning .admonition-title {
-    color:#FF0000;
+#docs-body h3 {
+  font-size:1.4em;
 }
 
-div.admonition .admonition-title {
-    font-weight:bold;
+/* SQL popup, code styles */
+
+.highlight {
+  background:none;
 }
 
+#docs-container pre {
+  font-size:1.2em;
+}
 
-.totoc {
- 
+#docs-container .pre {
+  font-size:1.1em;
 }
 
-.doc_copyright {
-    font-size:.85em;
-    padding:10px 0px 10px 0px;
+#docs-container pre {
+  background-color: #f0f0f0;  
+  border: solid 1px #ccc;
+  box-shadow: 2px 2px 3px #DFDFDF;
+  padding:10px;
+  margin: 5px 0px 5px 0px;
+  overflow:auto;
+  line-height:1.3em;
 }
 
-/* take out sphinx/pygments putting some kind
-of green background here... */
-.highlight {
-  background:none;
+.popup_sql, .show_sql
+{
+    background-color: #FBFBEE;
+    padding:5px 10px;
+    margin:10px -5px;
+    border:1px dashed;
 }
 
-pre {
-	background-color: #f0f0f0;	
-	border: solid 1px #ccc;
-	padding:10px;
-	margin: 5px 5px 5px 5px;
-	overflow:auto;
-	line-height:1.3em;
+/* the [SQL] links used to display SQL */
+#docs-container .sql_link
+{
+  font-weight:normal;
+  font-family: arial, sans-serif;
+  font-size:.9em;
+  text-transform: uppercase;
+  color:#990000;
+  border:1px solid;
+  padding:1px 2px 1px 2px;
+  margin:0px 10px 0px 15px;
+  float:right;
+  line-height:1.2em;
+}
+
+#docs-container a.sql_link, 
+#docs-container .sql_link
+{
+    text-decoration: none;
+    padding:1px 2px;
 }
 
-.versionheader {
-    margin-top: 0.5em;
+#docs-container a.sql_link:hover {
+    text-decoration: none;
+    color:#fff;
+    border:1px solid #900;
+    background-color: #900;
 }
-.versionnum {
-    font-weight: bold;
+
+/* docutils-specific elements */
+
+th.field-name {
+    text-align:right;
+}
+
+div.note, div.warning, p.deprecated, div.topic  {
+    background-color:#EEFFEF;
+}
+
+
+div.admonition, div.topic, p.deprecated {
+    border:1px solid #CCCCCC;
+    padding:5px 10px;
+    font-size:.9em;
+    box-shadow: 2px 2px 3px #DFDFDF;
+}
+
+div.warning .admonition-title {
+    color:#FF0000;
+}
+
+div.admonition .admonition-title, div.topic .topic-title {
+    font-weight:bold;
 }
 
 .viewcode-back, .viewcode-link {
     float:right;
 }
-.prerelease {
-    border: solid #c25757 2px;
-    border-radius: 4px;
-    -moz-border-radius: 4px;
-    -webkit-border-radius: 4px;
-    background-color: #c21a1a;
-    color: white;
-    padding: 0.05em 0.2em;
-}
 
 dl.function > dt,
 dl.attribute > dt,
@@ -229,7 +333,7 @@ dl.class > dt,
 dl.exception > dt
 {
     background-color:#F0F0F0;
-    margin:0px -10px;
+    margin:25px -10px 10px 10px;
     padding: 0px 10px;
 }
 
@@ -279,16 +383,50 @@ tt {
     padding:0 1px;
 }
 
-@media print {
-  #nav { display: none; }
-  #pagecontrol { display: none; }
-  .topnav .prevnext { display: none; }
-  .bottomnav { display: none; }
-  .totoc { display: none; }
-  .topnav ul li a { text-decoration: none; color: #000; }
-}
-
 /* syntax highlighting overrides */
 .k, .kn {color:#0908CE;}
 .o {color:#BF0005;}
 .go {color:#804049;}
+
+
+/* special "index page" sections 
+   with specific formatting
+*/
+
+div#sqlalchemy-documentation {
+  font-size:.95em;
+}
+div#sqlalchemy-documentation em {
+  font-style:normal;
+}
+div#sqlalchemy-documentation .rubric{
+  font-size:14px;
+  background-color:#EEFFEF;
+  padding:5px;
+  border:1px solid #BFBFBF;
+}
+div#sqlalchemy-documentation a, div#sqlalchemy-documentation li {
+  padding:5px 0px;
+}
+
+div#getting-started {
+  border-bottom:1px solid;
+}
+
+div#sqlalchemy-documentation div#sqlalchemy-orm {
+  float:left;
+  width:48%;
+}
+
+div#sqlalchemy-documentation div#sqlalchemy-core {
+  float:left;
+  width:48%;
+  margin:0;
+  padding-left:10px;
+  border-left:1px solid;
+}
+
+div#dialect-documentation {
+  border-top:1px solid;
+  /*clear:left;*/
+}
diff --git a/doc/build/syntax.rst b/doc/build/syntax.rst
index 7305d58..f98fca1 100644
--- a/doc/build/syntax.rst
+++ b/doc/build/syntax.rst
@@ -365,7 +365,7 @@ offers a lot of flexbility in this area, including dynamic
 inheritance, content wrapping, and polymorphic method calls.
 Check it out in :ref:`inheritance_toplevel`.
 
-<%namespacename:defname>
+<%nsname:defname>
 -------------------------
 
 As of Mako 0.2.3, any user-defined "tag" can be created against
diff --git a/doc/build/templates/layout.mako b/doc/build/templates/layout.mako
index 59c3f07..5f21ef9 100644
--- a/doc/build/templates/layout.mako
+++ b/doc/build/templates/layout.mako
@@ -1,6 +1,32 @@
 ## coding: utf-8
+
+<%doc>
+    Structural elements are all prefixed with "docs-"
+    to prevent conflicts when the structure is integrated into the 
+    main site.
+    
+    docs-container ->
+        docs-header ->
+            docs-search
+            docs-version-header
+        docs-top-navigation
+            docs-top-page-control
+            docs-navigation-banner
+        docs-body-container ->
+            docs-sidebar
+            docs-body
+        docs-bottom-navigation
+            docs-copyright
+</%doc>
+
 <%inherit file="${context['mako_layout']}"/>
 
+<%
+withsidebar = bool(toc) and current_page_name != 'index'
+%>
+
+<div id="docs-container">
+
 <%block name="headers">
     <link rel="stylesheet" href="${pathto('_static/pygments.css', 1)}" type="text/css" />
     <link rel="stylesheet" href="${pathto('_static/docs.css', 1)}" type="text/css" />
@@ -35,95 +61,133 @@
     % if prevtopic:
         <link rel="prev" title="${prevtopic['title']|util.striptags}" href="${prevtopic['link']|h}" />
     % endif
-
-    <%block name="extrahead">
-    </%block>
 </%block>
 
-        <h1>${docstitle|h}</h1>
+<div id="docs-header">
+    <h1>${docstitle|h}</h1>
 
-        <div id="search">
-        Search:
-        <form class="search" action="${pathto('search')}" method="get">
-          <input type="text" name="q" size="18" /> <input type="submit" value="${_('Search')}" />
-          <input type="hidden" name="check_keywords" value="yes" />
-          <input type="hidden" name="area" value="default" />
-        </form>
-        </div>
+    <div id="docs-search">
+    Search:
+    <form class="search" action="${pathto('search')}" method="get">
+      <input type="text" name="q" size="18" /> <input type="submit" value="${_('Search')}" />
+      <input type="hidden" name="check_keywords" value="yes" />
+      <input type="hidden" name="area" value="default" />
+    </form>
+    </div>
 
-        <div class="versionheader">
-            Version: <span class="versionnum">${release}</span> Last Updated: ${last_updated}
-        </div>
-        <div class="clearboth"></div>
-
-        <div class="topnav">
-            <div id="pagecontrol">
-                <a href="${pathto('genindex')}">Index</a>
- 
-                % if sourcename:
-                <div class="sourcelink">(<a href="${pathto('_sources/' + sourcename, True)|h}">${_('view source')})</div>
-                % endif
-            </div>
- 
-            <div class="navbanner">
-                <a class="totoc" href="${pathto(master_doc)}">Table of Contents</a>
-                % if parents:
-                    % for parent in parents:
-                        » <a href="${parent['link']|h}" title="${parent['title']}">${parent['title']}</a>
-                    % endfor
-                % endif
-                % if current_page_name != master_doc:
-                » ${self.show_title()} 
-                % endif
-
-                ${prevnext()}
-                <h2>
-                    <%block name="show_title" filter="util.striptags">
-                    % if title:
-                        ${title}
-                    % endif
-                    </%block>
-                </h2>
-            </div>
-            % if display_toc and not current_page_name.startswith('index'):
-                ${toc}
+    <div id="docs-version-header">
+        Release: <span class="version-num">${release}</span>
+
+    </div>
+
+</div>
+
+<div id="docs-top-navigation">
+    <div id="docs-top-page-control" class="docs-navigation-links">
+        <ul>
+        % if prevtopic:
+            <li>Prev:
+            <a href="${prevtopic['link']|h}" title="${_('previous chapter')}">${prevtopic['title']}</a>
+            </li>
+        % endif
+        % if nexttopic:
+            <li>Next:
+            <a href="${nexttopic['link']|h}" title="${_('next chapter')}">${nexttopic['title']}</a>
+            </li>
+        % endif
+
+        <li>
+            <a href="${pathto('index')}">Table of Contents</a> |
+            <a href="${pathto('genindex')}">Index</a>
+            % if sourcename:
+            | <a href="${pathto('_sources/' + sourcename, True)|h}">${_('view source')}
             % endif
-            <div class="clearboth"></div>
-        </div>
- 
-        <div class="document">
-            <div class="body">
-                ${next.body()}
-            </div>
-        </div>
+        </li>
+        </ul>
+    </div>
+
+    <div id="docs-navigation-banner">
+        <a href="${pathto('index')}">${docstitle|h}</a>
+        % if parents:
+            % for parent in parents:
+                » <a href="${parent['link']|h}" title="${parent['title']}">${parent['title']}</a>
+            % endfor
+        % endif
+        % if current_page_name != 'index':
+        » ${self.show_title()} 
+        % endif
+
+        <h2>
+            <%block name="show_title">
+            % if title:
+                ${title}
+            % endif
+            </%block>
+        </h2>
+    </div>
+
+</div>
+
+<div id="docs-body-container">
+
+% if withsidebar:
+    <div id="docs-sidebar">
+    <h3><a href="${pathto('index')}">Table of Contents</a></h3>
+    ${toc}
 
-        <%block name="footer">
-            <div class="bottomnav">
-                ${prevnext()}
-                <div class="doc_copyright">
-                % if hasdoc('copyright'):
-                    &copy; <a href="${pathto('copyright')}">Copyright</a> ${copyright|h}.
-                % else:
-                    &copy; Copyright ${copyright|h}.
-                % endif
-                % if show_sphinx:
-                    Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> ${sphinx_version|h}.
-                % endif
-                </div>
-            </div>
-        </%block>
-
-<%def name="prevnext()">
-<div class="prevnext">
     % if prevtopic:
-        Previous:
-        <a href="${prevtopic['link']|h}" title="${_('previous chapter')}">${prevtopic['title']}</a>
+    <h4>Previous Topic</h4>
+    <p>
+    <a href="${prevtopic['link']|h}" title="${_('previous chapter')}">${prevtopic['title']}</a>
+    </p>
     % endif
     % if nexttopic:
-        Next:
-        <a href="${nexttopic['link']|h}" title="${_('next chapter')}">${nexttopic['title']}</a>
+    <h4>Next Topic</h4>
+    <p>
+    <a href="${nexttopic['link']|h}" title="${_('next chapter')}">${nexttopic['title']}</a>
+    </p>
     % endif
+
+    <h4>Quick Search</h4>
+    <p>
+    <form class="search" action="${pathto('search')}" method="get">
+      <input type="text" name="q" size="18" /> <input type="submit" value="${_('Search')}" />
+      <input type="hidden" name="check_keywords" value="yes" />
+      <input type="hidden" name="area" value="default" />
+    </form>
+    </p>
+
+    </div>
+% endif
+
+    <div id="docs-body" class="${'withsidebar' if withsidebar else ''}" >
+        ${next.body()}
+    </div>
+
 </div>
-</%def>
 
+<%block name="footer">
+    <div id="docs-bottom-navigation" class="docs-navigation-links">
+        % if prevtopic:
+            Previous:
+            <a href="${prevtopic['link']|h}" title="${_('previous chapter')}">${prevtopic['title']}</a>
+        % endif
+        % if nexttopic:
+            Next:
+            <a href="${nexttopic['link']|h}" title="${_('next chapter')}">${nexttopic['title']}</a>
+        % endif
 
+        <div id="docs-copyright">
+        % if hasdoc('copyright'):
+            &copy; <a href="${pathto('copyright')}">Copyright</a> ${copyright|h}.
+        % else:
+            &copy; Copyright ${copyright|h}.
+        % endif
+        % if show_sphinx:
+            Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> ${sphinx_version|h}.
+        % endif
+        </div>
+    </div>
+</%block>
+
+</div>
diff --git a/doc/build/templates/site_base.mako b/doc/build/templates/site_base.mako
index 833293c..30ace37 100644
--- a/doc/build/templates/site_base.mako
+++ b/doc/build/templates/site_base.mako
@@ -1,17 +1,11 @@
 <%text>#coding:utf-8
-<%inherit file="/root.html"/>
+<%inherit file="/root.mako"/>
 <%page cache_type="file" cached="True"/>
 <%!
     in_docs=True
 %>
 </%text>
 
-<%doc>
-## TODO: pdf
-<div style="text-align:right">
-<b>PDF Download:</b> <a href="${pathto('sqlalchemy_' + release.replace('.', '_') + '.pdf', 1)}">download</a>
-</div>
-</%doc>
 
 ${'<%text>'}
 ${next.body()}