- a rework of doc layout and nav:

  - reduce the real estate for the top nav; move the search box
    into the top yellow box, close in space
  - use a new CSS/js approach such that the top toolbar freezes from
    scrolling at the top of the page.  The left nav scrolls independently
    of the content pane so that the local contents remain visible regardless
    of scrolling.   this approach is disabled on mobile where the dual scrollbars
    may be cumbersome (overall the site is not well designed for mobile).

6 files changed, 169 insertions, 79 deletions

diff --git a/doc/build/conf.py b/doc/build/conf.py
index 55db66801..b714fc579 100644
--- a/doc/build/conf.py
+++ b/doc/build/conf.py
@@ -96,7 +96,7 @@ release = "0.9.4"
 
 release_date = "March 28, 2014"
 
-site_base = "http://www.sqlalchemy.org"
+site_base = os.environ.get("RTD_SITE_BASE", "http://www.sqlalchemy.org")
 
 # arbitrary number recognized by builders.py, incrementing this
 # will force a rebuild
@@ -206,9 +206,11 @@ html_domain_indices = False
 
 # If true, the reST sources are included in the HTML build as _sources/<name>.
 #html_copy_source = True
+html_copy_source = False
 
 # If true, links to the reST sources are added to the pages.
 #html_show_sourcelink = True
+html_show_sourcelink = False
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
 #html_show_sphinx = True
diff --git a/doc/build/static/detectmobile.js b/doc/build/static/detectmobile.js
new file mode 100644
index 000000000..f86b2d650
--- /dev/null
+++ b/doc/build/static/detectmobile.js
@@ -0,0 +1,7 @@
+/**
+ * jQuery.browser.mobile (http://detectmobilebrowser.com/)
+ *
+ * jQuery.browser.mobile will be true if the browser is a mobile device
+ *
+ **/
+(function(a){(jQuery.browser=jQuery.browser||{}).mobile=/(android|bb\d+|meego).+mobile|avantgo|bada\/|blackberry|blazer|compal|elaine|fennec|hiptop|iemobile|ip(hone|od)|iris|kindle|lge |maemo|midp|mmp|mobile.+firefox|netfront|opera m(ob|in)i|palm( os)?|phone|p(ixi|re)\/|plucker|pocket|psp|series(4|6)0|symbian|treo|up\.(browser|link)|vodafone|wap|windows (ce|phone)|xda|xiino/i.test(a)||/1207|6310|6590|3gso|4thp|50[1-6]i|770s|802s|a wa|abac|ac(er|oo|s\-)|ai(ko|rn)|al(av|ca|co)|amoi|an(ex|ny|yw)|aptu|ar(ch|go)|as(te|us)|attw|au(di|\-m|r |s )|avan|be(ck|ll|nq)|bi(lb|rd)|bl(ac|az)|br(e|v)w|bumb|bw\-(n|u)|c55\/|capi|ccwa|cdm\-|cell|chtm|cldc|cmd\-|co(mp|nd)|craw|da(it|ll|ng)|dbte|dc\-s|devi|dica|dmob|do(c|p)o|ds(12|\-d)|el(49|ai)|em(l2|ul)|er(ic|k0)|esl8|ez([4-7]0|os|wa|ze)|fetc|fly(\-|_)|g1 u|g560|gene|gf\-5|g\-mo|go(\.w|od)|gr(ad|un)|haie|hcit|hd\-(m|p|t)|hei\-|hi(pt|ta)|hp( i|ip)|hs\-c|ht(c(\-| |_|a|g|p|s|t)|tp)|hu(aw|tc)|i\-(20|go|ma)|i230|iac( |\-|\/)|ibro|idea|ig01|ikom|im1k|inno|ipaq|iris|ja(t|v)a|jbro|jemu|jigs|kddi|keji|kgt( |\/)|klon|kpt |kwc\-|kyo(c|k)|le(no|xi)|lg( g|\/(k|l|u)|50|54|\-[a-w])|libw|lynx|m1\-w|m3ga|m50\/|ma(te|ui|xo)|mc(01|21|ca)|m\-cr|me(rc|ri)|mi(o8|oa|ts)|mmef|mo(01|02|bi|de|do|t(\-| |o|v)|zz)|mt(50|p1|v )|mwbp|mywa|n10[0-2]|n20[2-3]|n30(0|2)|n50(0|2|5)|n7(0(0|1)|10)|ne((c|m)\-|on|tf|wf|wg|wt)|nok(6|i)|nzph|o2im|op(ti|wv)|oran|owg1|p800|pan(a|d|t)|pdxg|pg(13|\-([1-8]|c))|phil|pire|pl(ay|uc)|pn\-2|po(ck|rt|se)|prox|psio|pt\-g|qa\-a|qc(07|12|21|32|60|\-[2-7]|i\-)|qtek|r380|r600|raks|rim9|ro(ve|zo)|s55\/|sa(ge|ma|mm|ms|ny|va)|sc(01|h\-|oo|p\-)|sdk\/|se(c(\-|0|1)|47|mc|nd|ri)|sgh\-|shar|sie(\-|m)|sk\-0|sl(45|id)|sm(al|ar|b3|it|t5)|so(ft|ny)|sp(01|h\-|v\-|v )|sy(01|mb)|t2(18|50)|t6(00|10|18)|ta(gt|lk)|tcl\-|tdg\-|tel(i|m)|tim\-|t\-mo|to(pl|sh)|ts(70|m\-|m3|m5)|tx\-9|up(\.b|g1|si)|utst|v400|v750|veri|vi(rg|te)|vk(40|5[0-3]|\-v)|vm40|voda|vulc|vx(52|53|60|61|70|80|81|83|85|98)|w3c(\-| )|webc|whit|wi(g |nc|nw)|wmlb|wonu|x700|yas\-|your|zeto|zte\-/i.test(a.substr(0,4))})(navigator.userAgent||navigator.vendor||window.opera);
\ No newline at end of file
diff --git a/doc/build/static/docs.css b/doc/build/static/docs.css
index b7c02248b..99858b429 100644
--- a/doc/build/static/docs.css
+++ b/doc/build/static/docs.css
@@ -1,8 +1,12 @@
 /* global */
 
+.body-background {
+  background-color: #FDFBFC;
+}
+
 body {
   background-color: #FDFBFC;
-  margin:38px;
+  margin:0 38px;
   color:#333333;
 }
 
@@ -61,6 +65,8 @@ a.headerlink:hover {
 
 #docs-container {
   max-width:1000px;
+  margin: 0 auto;
+  position: relative;
 }
 
 
@@ -77,7 +83,7 @@ a.headerlink:hover {
   font-family:Verdana,sans-serif;
 
   font-size:.9em;
-
+  position: relative;
 }
 
 #docs-top-navigation,
@@ -90,8 +96,15 @@ a.headerlink:hover {
 }
 
 #docs-top-navigation {
-  margin:10px 0px 10px 0px;
+  margin:10px 0px;
   line-height:1.2em;
+  position: relative;
+}
+
+#docs-version-header {
+  position: absolute;
+  right: 0;
+  bottom: 0;
 }
 
 .docs-navigation-links {
@@ -120,13 +133,10 @@ a.headerlink:hover {
     font-size:1.6em;
 }
 
-#docs-search {
-    float:right;
-}
-
 #docs-top-page-control {
-  float:right;
-  width:350px;
+  position: absolute;
+  right: 20px;
+  bottom: 14px;
 }
 
 #docs-top-page-control ul {
@@ -149,8 +159,6 @@ a.headerlink:hover {
 /* content container, sidebar */
 
 #docs-body-container {
-  background-color:#EFEFEF;
-  border: solid 1px #CCC;
 }
 
 #docs-body,
@@ -174,12 +182,63 @@ a.headerlink:hover {
 }
 
 #docs-sidebar {
-  float:left;
-  width:212px;
-  padding: 10px 0 0 15px;
+
+  width:210px;
+  padding: 0px 0 0 15px;
   font-size:.85em;
+
+  border: solid 1px #CCC;
+
+  z-index: 3;
+  background-color: #EFEFEF;
+
+  float: left;
+  top: 120px;
+  bottom: 0;
+  min-height: 0;
+  overflow-y: auto;
+}
+
+
+#docs-top-navigation-container {
+}
+
+#docs-top-navigation-container.automated {
+    position:fixed;
+    top:0;
+    z-index:100;
+    width:100%;
+}
+
+/* http://css-tricks.com/hash-tag-links-padding/ */
+#docs-container.preautomated div.section:before {
+    content: " ";
+    display: block;
+    height:120px;
+    margin-top: -120px;
+    visibility: hidden;
+}
+
+
+#docs-sidebar.preautomated:after {
+  content: " ";
+  display:block;
+  height: 150px;
 }
 
+
+#docs-sidebar.preautomated {
+  position: fixed;
+}
+
+#docs-sidebar.automated {
+    position: fixed;
+    float: none;
+    top: 120px;
+    min-height: 0;
+}
+
+
 #docs-sidebar h3, #docs-sidebar h4 {
     background-color: #DDDDDD;
     color: #222222;
@@ -189,7 +248,7 @@ a.headerlink:hover {
     margin: 10px 0 0 -15px;
     padding: 5px 10px 5px 10px;
     text-shadow: 1px 1px 0 white;
-    width:210px;
+    /*width:210px;*/
 }
 
 #docs-sidebar h3 a, #docs-sidebar h4 a {
@@ -212,11 +271,13 @@ a.headerlink:hover {
 #docs-body {
   background-color:#FFFFFF;
   padding:1px 10px 10px 10px;
+
+  border: solid 1px #CCC;
+
 }
 
 #docs-body.withsidebar {
   margin: 0 0 0 230px;
-  border-left:3px solid #DFDFDF;
 }
 
 #docs-body h1,
@@ -323,8 +384,8 @@ th.field-name {
 }
 
 div.section {
-  clear:right;
 }
+
 div.note, div.warning, p.deprecated, div.topic, div.admonition  {
     background-color:#EEFFEF;
 }
diff --git a/doc/build/static/init.js b/doc/build/static/init.js
index 1876d470e..5687eed1d 100644
--- a/doc/build/static/init.js
+++ b/doc/build/static/init.js
@@ -7,14 +7,62 @@ function initSQLPopups() {
     });
 }
 
-/*function initFloatyThings() {
-	$("dl.function, dl.class, dl.method, dl.attr, dl.data").each(function(idx, elem) {
-		$(elem).prepend("<div class='floatything'>" + $(elem).contents("dt").attr('id')+ "</div>");
-	});
-}*/
+var automatedBreakpoint = -1;
+
+function initFloatyThings() {
+
+    automatedBreakpoint = $("#docs-container").position().top;
+
+    parentOffset = $("#docs-container").parent().position().top - $("#docs-container").position().top;
+
+    // safari doesn't give us 120px for this CSS even though
+    // it's in docs.css as that
+    sidebarTop = "120px"; //$("#docs-sidebar").css("top");
+
+    $("#docs-top-navigation-container").addClass("preautomated");
+    $("#docs-sidebar").addClass("preautomated");
+    $("#docs-container").addClass("preautomated");
+
+    function setNavSize() {
+        $("#docs-top-navigation-container").css("width", $("#docs-container").width());
+    }
+
+    function setScroll() {
+
+        var scrolltop = $(window).scrollTop();
+        if (scrolltop >= automatedBreakpoint) {
+            setNavSize();
+            $("#docs-top-navigation-container").addClass("automated");
+            $("#docs-sidebar").addClass("automated");
+
+            // note this height is dependent on docs-top-navigation-container
+            // being position:fixed or absolute, otherwise it might get
+            // a little squashed
+            containerHeight = $("#docs-top-navigation-container").height();
+            $("#docs-body").css("margin-top", containerHeight - parentOffset + 1);
+            $("#docs-sidebar").css("top", sidebarTop);
+        }
+        else {
+            $("#docs-sidebar").removeClass("automated");
+            $("#docs-top-navigation-container").removeClass("automated");
+            $("#docs-body").css("margin-top", "");
+            // safari/chrome allow negative scroll positions
+            $("#docs-sidebar").css("top", $("#docs-body").offset().top - Math.max(scrolltop, 0));
+        }
+
+
+    }
+    $(window).scroll(setScroll)
+
+    $(window).resize(setNavSize());
+    setScroll();
+}
+
 
 $(document).ready(function() {
     initSQLPopups();
-    /*initFloatyThings();*/
+    if (!$.browser.mobile) {
+        initFloatyThings();
+    }
 });
 
diff --git a/doc/build/templates/layout.mako b/doc/build/templates/layout.mako
index a879fa481..b4659ce98 100644
--- a/doc/build/templates/layout.mako
+++ b/doc/build/templates/layout.mako
@@ -16,12 +16,12 @@
     main site.
 
     docs-container ->
-        docs-header ->
-            docs-search
-            docs-version-header
-        docs-top-navigation
-            docs-top-page-control
-            docs-navigation-banner
+        docs-top-navigation-container ->
+            docs-header ->
+                docs-version-header
+            docs-top-navigation
+                docs-top-page-control
+                docs-navigation-banner
         docs-body-container ->
             docs-sidebar
             docs-body
@@ -66,6 +66,7 @@ withsidebar = bool(toc) and current_page_name != 'index'
     % endfor
     <!-- end iterate through sphinx environment script_files -->
 
+    <script type="text/javascript" src="${pathto('_static/detectmobile.js', 1)}"></script>
     <script type="text/javascript" src="${pathto('_static/init.js', 1)}"></script>
     % if hasdoc('about'):
         <link rel="author" title="${_('About these documents')}" href="${pathto('about')}" />
@@ -89,51 +90,37 @@ withsidebar = bool(toc) and current_page_name != 'index'
 
 </%block>
 
-<div id="docs-header">
-    <h1>${docstitle|h}</h1>
-
-    <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 id="docs-top-navigation-container" class="body-background">
+<div id="docs-header">
     <div id="docs-version-header">
         Release: <span class="version-num">${release}</span> | Release Date: ${release_date}
-
-        % if pdf_url:
-        | <a href="${pdf_url}">Download PDF</a>
-        % endif
-
     </div>
 
-</div>
+    <h1>${docstitle|h}</h1>
 
+</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>
+            <a href="${prevtopic['link']|h}" title="${prevtopic['title']}">Prev</a> |
         % endif
         % if nexttopic:
-            <li>Next:
-            <a href="${nexttopic['link']|h}" title="${_('next chapter')}">${nexttopic['title']}</a>
-            </li>
+            <a href="${nexttopic['link']|h}" title="${nexttopic['title']}">Next</a> |
+        % endif
+
+        <a href="${pathto('index')}">Contents</a> |
+        <a href="${pathto('genindex')}">Index</a>
+        % if pdf_url:
+        | <a href="${pdf_url}">PDF</a>
         % endif
 
-        <li>
-            <a href="${pathto('contents')}">Table of Contents</a> |
-            <a href="${pathto('genindex')}">Index</a>
-            % if sourcename:
-            | <a href="${pathto('_sources/' + sourcename, True)|h}">${_('view source')}
-            % endif
-        </li>
-        </ul>
+        | <form class="search" action="${pathto('search')}" method="get">
+          <input type="text" name="q" size="12" /> <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-navigation-banner">
@@ -155,11 +142,13 @@ withsidebar = bool(toc) and current_page_name != 'index'
     </div>
 
 </div>
+</div>
 
 <div id="docs-body-container">
 
 % if withsidebar:
     <div id="docs-sidebar">
+
     <h3><a href="${pathto('index')}">Table of Contents</a></h3>
     ${toc}
 
@@ -182,14 +171,6 @@ withsidebar = bool(toc) and current_page_name != 'index'
     </ul>
     % 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
diff --git a/doc/build/templates/search.mako b/doc/build/templates/search.mako
index 83a3fcd84..d0aa3d825 100644
--- a/doc/build/templates/search.mako
+++ b/doc/build/templates/search.mako
@@ -14,15 +14,6 @@
     </script>
 </%block>
 
-<div id="searchform">
-<h3>Enter Search Terms:</h3>
-<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="search-results"></div>
 
 <%block name="footer">