From: Mike Bayer Date: Wed, 28 May 2014 14:56:52 +0000 (-0400) Subject: - a rework of doc layout and nav: X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5b8bbd8bc0179b7ea978f7598890cb73c19d02e6;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git - 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). --- diff --git a/doc/build/conf.py b/doc/build/conf.py index 8aa2c86771..5d280133b4 100644 --- a/doc/build/conf.py +++ b/doc/build/conf.py @@ -88,7 +88,7 @@ release = "0.7.10" release_date = "February 7, 2013" -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 @@ -198,9 +198,11 @@ html_domain_indices = False # If true, the reST sources are included in the HTML build as _sources/. #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 0000000000..f86b2d6507 --- /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 c0dbdcb289..7e9a26e6bc 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,9 +159,6 @@ a.headerlink:hover { /* content container, sidebar */ #docs-body-container { - background-color:#EFEFEF; - border: solid 1px #CCC; - } #docs-body, @@ -171,12 +178,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; @@ -186,7 +244,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 { @@ -209,11 +267,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, diff --git a/doc/build/static/init.js b/doc/build/static/init.js index cd4dac6b91..5687eed1dd 100644 --- a/doc/build/static/init.js +++ b/doc/build/static/init.js @@ -4,10 +4,65 @@ function initSQLPopups() { $('a.sql_link').click(function() { $(this).nextAll('div.popup_sql:first').toggle(); return false; - }) + }); } +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(); + if (!$.browser.mobile) { + initFloatyThings(); + } }); diff --git a/doc/build/templates/layout.mako b/doc/build/templates/layout.mako index a879fa4819..b4659ce986 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 + % if hasdoc('about'): @@ -89,51 +90,37 @@ withsidebar = bool(toc) and current_page_name != 'index' -
-

${docstitle|h}

- - +
+
Release: ${release} | Release Date: ${release_date} - - % if pdf_url: - | Download PDF - % endif -
-
+

${docstitle|h}

+
- + |
+ + + +
+
@@ -155,11 +142,13 @@ withsidebar = bool(toc) and current_page_name != 'index'
+
% if withsidebar:
+

Table of Contents

${toc} @@ -182,14 +171,6 @@ withsidebar = bool(toc) and current_page_name != 'index' % endif -

Quick Search

-

-

- - - -
-

% endif diff --git a/doc/build/templates/search.mako b/doc/build/templates/search.mako index 83a3fcd84a..d0aa3d8259 100644 --- a/doc/build/templates/search.mako +++ b/doc/build/templates/search.mako @@ -14,15 +14,6 @@ -
-

Enter Search Terms:

-
- - - -
-
-
<%block name="footer">