Add 3 + 4th levels to nav and more intuitive scrolling

Adds l3 + l4 nav menus, with more intuitive scrolling to make wandering the
additional nav menu items much easier. Resolves #25. Resolves #76.

* Reuses some styles for l3 + l4 navs items
* Nav interaction was changed to be more intuitive:
  * Nav is always sticky, doesn't scroll past end of content
  * Nav scrolls up immediately on window scroll events
  * Nav scrolls independently
  * Adds TOC expand plus links to the left of nav elements with children, these
    are added and update dynamically
  * Links in nav don't automatically scroll nav
  * Scrolling content will start scrolling nav again
  * Adds URL fragment handling to link and show current anchor links

demo_docs/source/long.rst

@@ -122,3 +122,88 @@ Example Menu 20
 ---------------
 
 Just a place holder...
+
+Example Submenu 1
+-----------------
+
+Just a place holder...
+
+Submenu 1
+~~~~~~~~~
+
+Just a place holder...
+
+Subsubmenu 1
+````````````
+
+Just a place holder...
+
+Subsubmenu 2
+````````````
+
+Just a place holder...
+
+Submenu 2
+~~~~~~~~~
+
+Just a place holder...
+
+Subsubmenu 1
+````````````
+
+Just a place holder...
+
+Submenu 3
+~~~~~~~~~
+
+Just a place holder...
+
+Submenu 4
+~~~~~~~~~
+
+Just a place holder...
+
+Submenu 5
+~~~~~~~~~
+
+Just a place holder...
+
+Example Submenu 2
+-----------------
+
+Just a place holder...
+
+Submenu 1
+~~~~~~~~~
+
+Just a place holder...
+
+Subsubmenu 1
+````````````
+
+Just a place holder...
+
+Submenu 2
+~~~~~~~~~
+
+Just a place holder...
+
+Subsubmenu 1
+````````````
+
+Just a place holder...
+
+Submenu 3
+~~~~~~~~~
+
+Just a place holder...
+
+Submenu 4
+~~~~~~~~~
+
+Just a place holder...
+
+Submenu 5
+~~~~~~~~~
+
+Just a place holder...

sass/_theme_layout.sass

@@ -58,6 +58,17 @@
       color: inherit
       padding-left: 0
       padding-right: 0
+    // Expand links
+    span.toctree-expand
+      display: block
+      float: left
+      margin-left: -1.2em
+      @extend .fa
+      @extend .fa-plus-square-o
+      font-size: .8em
+      line-height: 1.6em
+      color: darken($text-medium, 20%)
+
   // On state for the first level
   li.on a, li.current > a
     color: $text-color
@@ -72,16 +83,54 @@
     +font-smooth
     &:hover
       background: $section-background-color
+      span.toctree-expand
+        color: $text-medium
+    span.toctree-expand
+      @extend .fa
+      @extend .fa-minus-square-o
+      display: block
+      font-size: .8em
+      line-height: 1.6em
+      color: darken($text-medium, 30%)
+
   // This is the on state for pages beyond second level
-  li.toctree-l2.current > a
-    background: darken($section-background-color, 20%)
-    padding: $gutter / 4 $gutter * 1.5
-  li.toctree-l2 li.toctree-l3 > a
-    display: none
-  li.toctree-l2.current li.toctree-l3 > a
-    display: block
-    background: darken($section-background-color, 20%)
-    padding: $gutter / 4 $gutter * 2.5
+  li.toctree-l1.current li.toctree-l2, li.toctree-l2.current li.toctree-l3
+    > ul
+      display: none
+    &.current > ul
+      display: block
+  li.toctree-l2
+    &.current
+      > a
+        background: darken($section-background-color, 20%)
+        padding: $gutter / 4 $gutter * 1.5
+      li.toctree-l3 > a
+        display: block
+        background: darken($section-background-color, 20%)
+        padding: $gutter / 4 $gutter * 2.5
+    a:hover span.toctree-expand
+      color: $text-medium
+    span.toctree-expand
+      color: darken($section-background-color, 35%)
+  li.toctree-l3
+    font-size: .9em
+    &.current
+      > a
+        background: darken($section-background-color, 25%)
+        padding: $gutter / 4 $gutter * 2.5
+      li.toctree-l4 > a
+        display: block
+        background: darken($section-background-color, 25%)
+        padding: $gutter / 4 $gutter * 3.5
+        border-top: none
+        border-bottom: none
+    a:hover span.toctree-expand
+      color: $text-medium
+    span.toctree-expand
+      color: darken($section-background-color, 40%)
+  li.toctree-l4
+    font-size: .9em
+
   li.current ul
     display: block
   li ul
@@ -105,10 +154,14 @@
     &:hover
       background-color: lighten($menu-background-color, 10%)
       cursor: pointer
+      span.toctree-expand
+        color: $text-light
     &:active
       background-color: $menu-logo-color
       cursor: pointer
       color: $white
+      span.toctree-expand
+        color: $white
 
 .wy-side-nav-search
   z-index: $z-index-popover
@@ -193,11 +246,14 @@
   height: 100%
 
 .wy-nav-side
-  position: absolute
+  position: fixed
   top: 0
+  bottom: 0
   left: 0
+  padding-bottom: 2em
   width: $nav-desktop-width
-  overflow: hidden
+  overflow-x: hidden
+  overflow-y: scroll
   min-height: 100%
   background: $menu-background-color
   z-index: $z-index-popover
@@ -310,10 +366,3 @@ footer
     display: none
   .wy-nav-content-wrap
     margin-left: 0
-
-nav.stickynav
-  position: fixed
-  top: 0
-  bottom: 0
-  overflow-x: hidden
-  overflow-y: hidden

sphinx_rtd_theme/layout.html

@@ -107,7 +107,7 @@
 
       <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
         {% block menu %}
-          {% set toctree = toctree(maxdepth=2, collapse=False, includehidden=True) %}
+          {% set toctree = toctree(maxdepth=4, collapse=False, includehidden=True) %}
           {% if toctree %}
               {{ toctree }}
           {% else %}

sphinx_rtd_theme/static/js/theme.js

@@ -1,50 +1,113 @@
-$( document ).ready(function() {
+function toggleCurrent (elem) {
+    var parent_li = elem.closest('li');
+    parent_li.siblings('li.current').removeClass('current');
+    parent_li.siblings().find('li.current').removeClass('current');
+    parent_li.find('> ul li.current').removeClass('current');
+    parent_li.toggleClass('current');
+}
+
+$(document).ready(function() {
     // Shift nav in mobile when clicking the menu.
     $(document).on('click', "[data-toggle='wy-nav-top']", function() {
-      $("[data-toggle='wy-nav-shift']").toggleClass("shift");
-      $("[data-toggle='rst-versions']").toggleClass("shift");
+        $("[data-toggle='wy-nav-shift']").toggleClass("shift");
+        $("[data-toggle='rst-versions']").toggleClass("shift");
     });
-    // Close menu when you click a link.
+    // Nav menu link click operations
     $(document).on('click', ".wy-menu-vertical .current ul li a", function() {
-      $("[data-toggle='wy-nav-shift']").removeClass("shift");
-      $("[data-toggle='rst-versions']").toggleClass("shift");
+        var target = $(this);
+        // Close menu when you click a link.
+        $("[data-toggle='wy-nav-shift']").removeClass("shift");
+        $("[data-toggle='rst-versions']").toggleClass("shift");
+        // Handle dynamic display of l3 and l4 nav lists
+        toggleCurrent(target);
+        if (typeof(window.SphinxRtdTheme) != 'undefined') {
+            window.SphinxRtdTheme.StickyNav.hashChange();
+        }
     });
     $(document).on('click', "[data-toggle='rst-current-version']", function() {
-      $("[data-toggle='rst-versions']").toggleClass("shift-up");
-    });  
+        $("[data-toggle='rst-versions']").toggleClass("shift-up");
+    });
     // Make tables responsive
     $("table.docutils:not(.field-list)").wrap("<div class='wy-table-responsive'></div>");
+
+    // Add expand links to all parents of nested ul
+    $('.wy-menu-vertical ul').siblings('a').each(function () {
+        var link = $(this);
+            expand = $('<span class="toctree-expand"></span>');
+        expand.on('click', function (ev) {
+            toggleCurrent(link);
+            ev.stopPropagation();
+            return false;
+        });
+        link.prepend(expand);
+    });
 });
 
+// Sphinx theme state
 window.SphinxRtdTheme = (function (jquery) {
     var stickyNav = (function () {
         var navBar,
             win,
-            stickyNavCssClass = 'stickynav',
             winScroll = false,
+            linkScroll = false,
+            winPosition = 0,
             enable = function () {
-                navBar.addClass(stickyNavCssClass);
-                win.on('scroll', function() { // set flag on scroll event
-                    winScroll = true;
+                init();
+                reset();
+                win.on('hashchange', reset);
+
+                // Set scrolling
+                win.on('scroll', function () {
+                    if (!linkScroll) {
+                        winScroll = true;
+                    }
                 });
-                // use setInterval to only handle a subset of scroll events so we don't kill scroll performance
-                setInterval(function() {
+                setInterval(function () {
                     if (winScroll) {
                         winScroll = false;
-                        navBar.scrollTop(win.scrollTop());
+                        var newWinPosition = win.scrollTop(),
+                            navPosition = navBar.scrollTop(),
+                            newNavPosition = navPosition + (newWinPosition - winPosition);
+                        navBar.scrollTop(newNavPosition);
+                        winPosition = newWinPosition;
                     }
-                }, 100);
+                }, 25);
             },
             init = function () {
                 navBar = jquery('nav.wy-nav-side:first');
-                win    = jquery(window);
+                win = jquery(window);
+            },
+            reset = function () {
+                // Get anchor from URL and open up nested nav
+                var anchor = encodeURI(window.location.hash);
+                if (anchor) {
+                    try {
+                        var link = $('.wy-menu-vertical')
+                            .find('[href="' + anchor + '"]');
+                        $('.wy-menu-vertical li.toctree-l1 li.current')
+                            .removeClass('current');
+                        link.closest('li.toctree-l2').addClass('current');
+                        link.closest('li.toctree-l3').addClass('current');
+                        link.closest('li.toctree-l4').addClass('current');
+                    }
+                    catch (err) {
+                        console.log("Error expanding nav for anchor", err);
+                    }
+                }
+            },
+            hashChange = function () {
+                linkScroll = true;
+                win.one('hashchange', function () {
+                    linkScroll = false;
+                });
             };
         jquery(init);
         return {
-            enable : enable
+            enable: enable,
+            hashChange: hashChange
         };
     }());
     return {
-        StickyNav : stickyNav
+        StickyNav: stickyNav
     };
 }($));