Merge remote-tracking branch 'snide/master' into move-javascript-to-bottom

README.rst

@@ -73,6 +73,10 @@ Also note that the table of contents is set with ``includehidden=true``. This al
 to set a hidden toc in your index file with the hidden_ property that will allow you
 to build a toc without it rendering in your index.
 
+By default, the navigation will "stick" to the screen as you scroll. However if your toc
+is vertically too large, it revert to static positioning. To disable the sticky nav
+alltogether change the setting in ``conf.py``.
+
 Contributing or modifying the theme
 ===================================
 

demo_docs/source/conf.py

@@ -106,7 +106,9 @@ html_theme = 'sphinx_rtd_theme'
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#html_theme_options = {}
+html_theme_options = {
+    # 'sticky_navigation' : True  # Set to False to disable the sticky nav while scrolling.
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 html_theme_path = ["../.."]

sass/_theme_layout.sass

@@ -287,3 +287,6 @@ footer
   .wy-nav-content-wrap
     margin-left: 0
 
+nav.stickynav
+  position: fixed
+  top: 0

sphinx_rtd_theme/layout.html

@@ -37,6 +37,15 @@
     <link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" />
   {% endif %}
 
+  {# STICKY NAVIGATION #}
+  {% if theme_sticky_navigation %}
+    <script type="text/javascript">
+        jQuery(function () {
+            SphinxRtdTheme.StickyNav.enable();
+        });
+    </script>
+  {% endif %}
+
   {% for cssfile in css_files %}
     <link rel="stylesheet" href="{{ pathto(cssfile, 1) }}" type="text/css" />
   {% endfor %}

sphinx_rtd_theme/static/js/theme.js

@@ -14,3 +14,50 @@ $( document ).ready(function() {
   });
   $("table.docutils:not(.field-list").wrap("<div class='wy-table-responsive'></div>");
 });
+
+window.SphinxRtdTheme = (function (jquery) {
+
+    var stickyNav = (function () {
+
+        var navBar,
+            win,
+            stickyNavCssClass = 'stickynav',
+
+            applyStickNav = function () {
+
+                if (navBar.height() <= win.height()) {
+
+                    navBar.addClass(stickyNavCssClass);
+
+                } else {
+
+                    navBar.removeClass(stickyNavCssClass);
+                }
+            },
+
+            enable = function () {
+
+                applyStickNav();
+
+                win.on('resize', applyStickNav);
+            },
+
+            init = function () {
+
+                navBar = jquery('nav.wy-nav-side:first');
+                win    = jquery(window);
+            };
+
+        jquery(init);
+
+        return {
+
+            enable : enable
+        };
+    }());
+
+    return {
+
+        StickyNav : stickyNav
+    };
+}($));

sphinx_rtd_theme/theme.conf

@@ -5,3 +5,4 @@ stylesheet = css/theme.css
 [options]
 typekit_id = hiw1hhg
 analytics_id = 
+sticky_navigation = False