doc styling rework

8 files changed, 329 insertions, 230 deletions

diff --git a/doc/build/core/index.rst b/doc/build/core/index.rst
index e239b0f63..80df49070 100644
--- a/doc/build/core/index.rst
+++ b/doc/build/core/index.rst
@@ -3,6 +3,11 @@
 SQLAlchemy Core
 ===============
 
+The breadth of SQLAlchemy’s SQL rendering engine, DBAPI integration,
+transaction integration, and schema description services are documented here.
+In contrast to the ORM’s domain-centric mode of usage, the SQL Expression
+Language provides a schema-centric usage paradigm.
+
 .. toctree::
     :maxdepth: 2
 
diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst
index edd0a8b7e..bcdd0403c 100644
--- a/doc/build/core/tutorial.rst
+++ b/doc/build/core/tutorial.rst
@@ -4,9 +4,6 @@
 SQL Expression Language Tutorial
 ================================
 
-Introduction
-=============
-
 The SQLAlchemy Expression Language presents a system of representing
 relational database structures and expressions using Python constructs. These
 constructs are modeled to resemble those of the underlying database as closely
diff --git a/doc/build/orm/index.rst b/doc/build/orm/index.rst
index fee4e3de5..ac18f5d0f 100644
--- a/doc/build/orm/index.rst
+++ b/doc/build/orm/index.rst
@@ -3,6 +3,11 @@
 SQLAlchemy ORM
 ===============
 
+Here, the Object Relational Mapper is introduced and fully described. If you
+want to work with higher-level SQL which is constructed automatically for you,
+as well as automated persistence of Python objects, proceed first to the
+tutorial.
+
 .. toctree::
     :maxdepth: 2
 
diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst
index fd006d139..81c6be8dc 100644
--- a/doc/build/orm/tutorial.rst
+++ b/doc/build/orm/tutorial.rst
@@ -4,9 +4,6 @@
 Object Relational Tutorial
 ==========================
 
-Introduction
-============
-
 The SQLAlchemy Object Relational Mapper presents a method of associating
 user-defined Python classes with database tables, and instances of those
 classes (objects) with rows in their corresponding tables. It includes a
diff --git a/doc/build/static/docs.css b/doc/build/static/docs.css
index e338590ad..1169a8a97 100644
--- a/doc/build/static/docs.css
+++ b/doc/build/static/docs.css
@@ -1,248 +1,240 @@
+/* global */
+
 body {
   background-color: #FDFBFC;
   margin:38px;
   color:#333333;
 }
 
-body, td {
-  font-family: verdana, sans-serif;
-  font-size:.9em;
-}
-
-h1, h2, h3, h4, h5 {
-  font-family:Tahoma,Geneva,sans-serif;
-  font-weight:normal;
-  font-family:arial,Helvetica, sans-serif;
-  font-weight:bold;
+a {
+    font-weight:normal; 
+    text-decoration:none;
 }
 
-h1 {
-    font-size:20px;
-    line-height:22px;
-    color: #222222;
-    font-family:arial,Helvetica, sans-serif;
-    font-weight:normal;
-    margin: 0;
-    padding: 0;
-}
-h1, #topnav h2 {
-  font-family:Tahoma,Geneva,sans-serif;
-  font-weight:normal;
-}
 form {
     display:inline;
 }
 
-p {
-  margin-top:10px;
-  margin-bottom:10px;
-}
-
-a {
-    font-weight:normal; 
-    text-decoration:none;
-}
+/* hyperlinks */
 
 a:link, a:visited, a:active {
-    color:#0000FF;
+    /*color:#0000FF;*/
+    color: #990000;
 }
 a:hover {
-    color:#700000;
+    color: #FF0000;
+    /*color:#700000;*/
+    text-decoration:underline;
 }
 
-strong a {
-    font-weight: bold;
-}
+/* paragraph links after sections.
+   These aren't visible until hovering
+   over the <h> tag, then have a 
+   "reverse video" effect over the actual
+   link
+ */
 
-.document {
-  border: solid 1px #ccc;
+a.headerlink {
+    font-size: 0.8em;
+    padding: 0 4px 0 4px;
+    text-decoration: none;
+    visibility: hidden;
 }
 
-.document h1, .document h2, .document h3, .document h4, .document h5 {
-    font-size: 1.4em;
+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;
 }
 
-.document img {
-    display:block;
-    margin: 0 auto;
+a.headerlink:hover {
+    background-color: #990000;
+    color: white;
 }
 
-.document h1 {
-    display:none;
+
+/* Container setup */
+
+#docs-container {
+  max-width:1000px;
 }
 
 
-/* standard page elements */
-#search {
-    float:right;
+/* header/footer elements */
+
+#docs-header h1 {
+    font-size:20px;
+    color: #222222;
+    margin: 0;
+    padding: 0;
 }
 
-#searchform {
-    padding:20px;
+#docs-header {
+  font-family:Verdana,sans-serif;
+
+  font-size:.9em;
+
 }
 
-#navbanner {
+#docs-top-navigation,
+#docs-bottom-navigation {
+  font-family: Verdana, sans-serif;
+  background-color: #FBFBEE;
+  border: solid 1px #CCC;
+  padding:10px;
+  font-size:.8em;
 }
 
-#pagecontrol {
-  float:right;
-  width:300px;
+#docs-top-navigation {
+  margin:10px 0px 10px 0px;
+  line-height:1.2em;
 }
 
-#pagecontrol ul {
-  padding:0;
-  margin:0;
+.docs-navigation-links {
+  font-family:Verdana,sans-serif;
 }
-#pagecontrol li {
-    font-size:.9em;
-    list-style-type:none;
-    margin:0px;
-    padding:1px 8px;
+
+#docs-bottom-navigation {
+    float:right;
+    margin: 1em 0 1em 5px;
 }
 
-#topnav {
-  background-color: #fbfbee;
-  border: solid 1px #ccc;
-  padding:10px;
-  margin:10px 0px 10px 0px;
-  display:block;
+#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;
 }
 
-#topnav h2 {
-    margin:8px 4px 0px 5px;
+#docs-top-navigation h2 {
+    margin:16px 4px 7px 5px;
     font-size:1.6em;
-    font-weight:normal;
-    line-height:1.6em;
 }
 
-#topnav h3 {
-    font-weight: bold;
-    font-size: 1.4em;
-    margin:0px;
-    display:inline;
+#docs-search {
+    float:right;
 }
 
-#navbanner li,
-li.toctree-l1,
-li.toctree-l1 li
-{
-    list-style-type:disc;
-    margin:0px;
-    padding:1px 8px;
+#docs-top-page-control {
+  float:right;
+  width:350px;
 }
 
-
-#topnav li ul, 
-li.toctree-l1 ul
-{
-    padding:0px 0px 0px 20px;
+#docs-top-page-control ul {
+  padding:0;
+  margin:0;
 }
 
-#topnav li ul li li, 
-li.toctree-l1 ul li li {
+#docs-top-page-control li {
+    font-size:.9em;
+    list-style-type:none;
+    padding:1px 8px;
 }
 
-.versionheader {
-    margin-top: 0.5em;
-}
-.versionnum {
+
+#docs-container .version-num {
     font-weight: bold;
 }
-.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;
-}
 
-.bottomnav {
-    background-color:#FBFBEE;
-    border:1px solid #CCCCCC;
-    float:right;
-    margin: 1em 0 1em 5px;
-    padding:10px;
-}
 
-.totoc {
+/* content container, sidebar */
 
-}
+#docs-body-container {
+  background-color:#EFEFEF;
+  border: solid 1px #CCC;
 
-.doc_copyright {
-    font-size:.85em;
-    padding:10px 0px 10px 0px;
 }
 
-/* ReST specific section padding */
+#docs-body,
+#docs-sidebar
+ {
+  /*font-family: helvetica, arial, sans-serif;
+  font-size:.9em;*/
+
+  font-family: Verdana, sans-serif;
+  font-size:.85em;
+  line-height:1.5em;
 
-.section ul {
-    padding: 0 0 0 25px;
 }
 
-.section {
-    line-height: 1.5em;
-    padding:0px 10px 20px 10px;
-    margin:10px 0px 0px;
+#docs-sidebar > ul {
+  font-size:.85em;
 }
 
-.section .section {
-    margin:0px 0px 0px 0px;
-    padding: 0px;
+#docs-sidebar {
+  float:left;
+  width:212px;
+  padding: 10px 0 0 15px;
+  font-size:.85em;
 }
 
-.section .section .section {
-    margin:0px 0px 0px 20px;
+#docs-sidebar h3, #docs-sidebar h4 {
+    background-color: #DDDDDD;
+    color: #222222;
+    font-family: Verdana,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 .section .section {
-    margin:0px 0px 0px 20px;
+#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;
 }
 
-/* special index sections */
 
-div#sqlalchemy-documentation {
-  font-size:.95em;
-}
-div#sqlalchemy-documentation em {
-  font-style:normal;
+#docs-sidebar ul ul {
+    margin-bottom: 0;
+    margin-top: 0;
+    list-style: square outside none;
+    margin-left: 20px;
 }
-div#sqlalchemy-documentation .rubric{
-  font-size:14px;
-  background-color:#EEFFEF;
-  padding:5px;
-  border:1px solid #BFBFBF;
+
+#docs-body {
+  background-color:#FFFFFF;
+  padding:1px 10px 10px 10px;
 }
-div#sqlalchemy-documentation a, div#sqlalchemy-documentation li {
-  padding:5px 0px;
+
+#docs-body.withsidebar {
+  margin: 0 0 0 230px;
+  border-left:3px solid #DFDFDF;
 }
 
-div#getting-started {
-  border-bottom:1px solid;
+#docs-body h1,
+#docs-body h2,
+#docs-body h3,
+#docs-body h4 {
+  font-family:Helvetica, Arial, sans-serif;
 }
 
-div#sqlalchemy-documentation div#sqlalchemy-orm {
-  float:left;
-  width:48%;
+#docs-body h1 {
+  /* hide the <h1> for each content section. */
+  display:none;
+  font-size:1.8em;
 }
 
-div#sqlalchemy-documentation div#sqlalchemy-core {
-  float:left;
-  width:48%;
-  margin:0;
-  padding-left:10px;
-  border-left:1px solid;
+#docs-body h2 {
+  font-size:1.6em;
 }
 
-div#dialect-documentation {
-  border-top:1px solid;
-  clear:left;
+#docs-body h3 {
+  font-size:1.4em;
 }
 
 /* SQL popup, code styles */
@@ -250,29 +242,41 @@ div#dialect-documentation {
 .highlight {
   background:none;
 }
-pre {
+
+#docs-container pre {
+  font-size:1.2em;
+}
+
+#docs-container .pre {
+  font-size:1.1em;
+}
+
+#docs-container pre {
   background-color: #f0f0f0;  
   border: solid 1px #ccc;
+  box-shadow: 2px 2px 3px #DFDFDF;
   padding:10px;
-  margin: 5px 5px 5px 5px;
+  margin: 5px 0px 5px 0px;
   overflow:auto;
   line-height:1.3em;
 }
 
 .popup_sql, .show_sql
 {
-    background-color: #fbfbee;
-    padding:0px 10px;
-    margin:0px -10px;
+    background-color: #FBFBEE;
+    padding:5px 10px;
+    margin:10px -5px;
+    border:1px dashed;
 }
 
-.sql_link
+/* the [SQL] links used to display SQL */
+#docs-container .sql_link
 {
   font-weight:normal;
   font-family: arial, sans-serif;
-    text-transform: uppercase;
-  font-size: 0.9em;
-  color:#666;
+  font-size:.9em;
+  text-transform: uppercase;
+  color:#990000;
   border:1px solid;
   padding:1px 2px 1px 2px;
   margin:0px 10px 0px 15px;
@@ -280,20 +284,21 @@ pre {
   line-height:1.2em;
 }
 
-#docs a.sql_link, .sql_link
+#docs-container a.sql_link, 
+#docs-container .sql_link
 {
     text-decoration: none;
     padding:1px 2px;
 }
 
-#docs a.sql_link:hover {
+#docs-container a.sql_link:hover {
     text-decoration: none;
     color:#fff;
     border:1px solid #900;
     background-color: #900;
 }
 
-/* other assorted ReST styles */
+/* docutils-specific elements */
 
 th.field-name {
     text-align:right;
@@ -306,9 +311,9 @@ div.note, div.warning, p.deprecated, div.topic  {
 
 div.admonition, div.topic, p.deprecated {
     border:1px solid #CCCCCC;
-    margin:5px 5px 5px 5px;
-    padding:5px 5px 5px 35px;
+    padding:5px 10px;
     font-size:.9em;
+    box-shadow: 2px 2px 3px #DFDFDF;
 }
 
 div.warning .admonition-title {
@@ -331,7 +336,7 @@ dl.class > dt,
 dl.exception > dt
 {
     background-color:#F0F0F0;
-    margin:0px -10px;
+    margin:25px -10px 10px 10px;
     padding: 0px 10px;
 }
 
@@ -381,16 +386,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/templates/layout.mako b/doc/build/templates/layout.mako
index a5e3d17c8..d34e4ef38 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" />
@@ -37,29 +63,36 @@
     % endif
 </%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">
-    Release: <span class="versionnum">${release}</span> | Release Date: ${release_date}
-    % if not version.startswith(versions[0][0]):
-    <div class="versionwarning">
-        The current version of SQLAlchemy is ${versions[0][0]}.   <a href="/docs/">View current SQLAlchemy Documentation</a>
+    <div id="docs-version-header">
+        Release: <span class="version-num">${release}</span> | Release Date: ${release_date}
+
+        % if self.attr.site_layout:
+            | <a href="${pathto('sqlalchemy_' + release.replace('.', '_') + '.pdf', 1)}">Download PDF</a>
+        % endif
+
+        % if self.attr.site_layout and not version.startswith(versions[0][0]):
+        <div class="version-warning">
+            The current version of SQLAlchemy is ${versions[0][0]}.   <a href="/docs/">View current SQLAlchemy Documentation</a>
+        </div>
+        % endif
     </div>
-    % endif
+
 </div>
-<div class="clearboth"></div>
 
-<div id="topnav">
-    <div id="pagecontrol">
+<div id="docs-top-navigation">
+    <div id="docs-top-page-control" class="docs-navigation-links">
         <ul>
         % if prevtopic:
             <li>Prev:
@@ -81,8 +114,9 @@ Search:
         </li>
         </ul>
     </div>
-    <div id="navbanner">
-        <a class="totoc" href="${pathto('index')}">${docstitle|h}</a>
+
+    <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>
@@ -99,23 +133,50 @@ Search:
             % endif
             </%block>
         </h2>
-    % if display_toc and \
-            not current_page_name.startswith('index') and \
-            not current_page_name.startswith('contents'):
-        ${toc}
-    % endif
     </div>
-    <div class="clearboth"></div>
+
 </div>
 
-<div class="document">
-    <div class="body">
+<div id="docs-body-container">
+
+% if withsidebar:
+    <div id="docs-sidebar">
+    <h3><a href="${pathto('index')}">Table of Contents</a></h3>
+    ${toc}
+
+    % if prevtopic:
+    <h4>Previous Topic</h4>
+    <p>
+    <a href="${prevtopic['link']|h}" title="${_('previous chapter')}">${prevtopic['title']}</a>
+    </p>
+    % endif
+    % if nexttopic:
+    <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>
 
 <%block name="footer">
-    <div class="bottomnav">
+    <div id="docs-bottom-navigation" class="docs-navigation-links">
         % if prevtopic:
             Previous:
             <a href="${prevtopic['link']|h}" title="${_('previous chapter')}">${prevtopic['title']}</a>
@@ -124,7 +185,8 @@ Search:
             Next:
             <a href="${nexttopic['link']|h}" title="${_('next chapter')}">${nexttopic['title']}</a>
         % endif
-        <div class="doc_copyright">
+
+        <div id="docs-copyright">
         % if hasdoc('copyright'):
             &copy; <a href="${pathto('copyright')}">Copyright</a> ${copyright|h}.
         % else:
@@ -137,4 +199,4 @@ Search:
     </div>
 </%block>
 
-
+</div>
diff --git a/doc/build/templates/site_base.mako b/doc/build/templates/site_base.mako
index de13d444d..88b1f6401 100644
--- a/doc/build/templates/site_base.mako
+++ b/doc/build/templates/site_base.mako
@@ -6,14 +6,6 @@
 %>
 </%text>
 
-<div style="text-align:right">
-<b>Jump to Version:</b> ${" | ".join('<a href="/docs/%s/">%s</a>' % (link, vers) for vers, link in versions)}
-</div>
-
-<div style="text-align:right">
-<b>PDF Download:</b> <a href="${pathto('sqlalchemy_' + release.replace('.', '_') + '.pdf', 1)}">download</a>
-</div>
-
 ${'<%text>'}
 ${next.body()}
 ${'</%text>'}
@@ -29,4 +21,5 @@ ${'</%text>'}
 
 <%!
     local_script_files = []
+    site_layout=True
 %>
diff --git a/doc/build/templates/static_base.mako b/doc/build/templates/static_base.mako
index c3be6d403..9454a1ead 100644
--- a/doc/build/templates/static_base.mako
+++ b/doc/build/templates/static_base.mako
@@ -16,4 +16,5 @@
 
 <%!
     local_script_files = []
+    site_layout=False
 %>