Resolve scrollbar visibility on navbar on long content

This resolves #200, where a scrollbar was sometimes visible on the navbar. This
unfortunately wasn't addressable with just CSS, as outlined in #206. Because we
need the element to be scrollable, we can't set `overflow: hidden` on the nav
element.

This fixes this issue by:

 * Adding a `wy-side-scroll` element over the fixed position nav element and
   under the menu item elements
 * `wy-side-scroll` is set to 320px width, while the fixed position nav elements
   and menu item elements are 300px, clipping the scrollbar with `overflow-x:
   hidden` on the fixed position element
 * Javascript is set to scroll the new scroll element instead of the parent
   fixed position element

This was tested to be working in both cases on a variety of platforms: Linux FF,
Chrome, Windows IE, OSX Chrome and Safari, iPhone 5.1, and Android 4.2.

sass/_theme_layout.sass

@@ -24,6 +24,7 @@
     padding: 0 $base-font-size
 
 .wy-menu-vertical
+  width: $nav-desktop-width
   header, p.caption
     height: $base-font-size * 2
     display: inline-block
@@ -164,6 +165,10 @@
         color: $menu-link-active
 
 .wy-side-nav-search
+  display: block
+  width: $nav-desktop-width
+  padding: $gutter / 2
+  margin-bottom: $gutter / 2
   z-index: $z-index-popover
   background-color: $nav-search-background-color
   text-align: center
@@ -259,11 +264,18 @@
   padding-bottom: 2em
   width: $nav-desktop-width
   overflow-x: hidden
-  overflow-y: scroll
+  overflow-y: hidden
   min-height: 100%
   background: $nav-background-color
   z-index: $z-index-popover
 
+.wy-side-scroll
+  width: $nav-desktop-width + 20px
+  position: relative
+  overflow-x: hidden
+  overflow-y: scroll
+  height: 100%
+
 .wy-nav-top
   display: none
   background: $link-color
@@ -355,6 +367,12 @@ footer
     &.shift
       width: 85%
       left: 0
+  .wy-side-scroll
+    width: auto
+  .wy-side-nav-search
+    width: auto
+  .wy-menu.wy-menu-vertical
+    width: auto
   .wy-nav-content-wrap
     margin-left: 0
     .wy-nav-content

sphinx_rtd_theme/layout.html

@@ -85,50 +85,51 @@
 
     {# SIDE NAV, TOGGLES ON MOBILE #}
     <nav data-toggle="wy-nav-shift" class="wy-nav-side">
-      <div class="wy-side-nav-search">
-        {% block sidebartitle %}
+      <div class="wy-side-scroll">
+        <div class="wy-side-nav-search">
+          {% block sidebartitle %}
 
-        {% if logo and theme_logo_only %}
-          <a href="{{ pathto(master_doc) }}">
-        {% else %}
-          <a href="{{ pathto(master_doc) }}" class="icon icon-home"> {{ project }}
-        {% endif %}
-
-        {% if logo %}
-          {# Not strictly valid HTML, but it's the only way to display/scale it properly, without weird scripting or heaps of work #}
-          <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" />
-        {% endif %}
-        </a>
-
-        {% if theme_display_version %}
-          {%- set nav_version = version %}
-          {% if READTHEDOCS and current_version %}
-            {%- set nav_version = current_version %}
-          {% endif %}
-          {% if nav_version %}
-            <div class="version">
-              {{ nav_version }}
-            </div>
-          {% endif %}
-        {% endif %}
-
-        {% include "searchbox.html" %}
-
-        {% endblock %}
-      </div>
-
-      <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
-        {% block menu %}
-          {% set toctree = toctree(maxdepth=4, collapse=theme_collapse_navigation, includehidden=True) %}
-          {% if toctree %}
-              {{ toctree }}
+          {% if logo and theme_logo_only %}
+            <a href="{{ pathto(master_doc) }}">
           {% else %}
-              <!-- Local TOC -->
-              <div class="local-toc">{{ toc }}</div>
+            <a href="{{ pathto(master_doc) }}" class="icon icon-home"> {{ project }}
           {% endif %}
-        {% endblock %}
+
+          {% if logo %}
+            {# Not strictly valid HTML, but it's the only way to display/scale it properly, without weird scripting or heaps of work #}
+            <img src="{{ pathto('_static/' + logo, 1) }}" class="logo" />
+          {% endif %}
+          </a>
+
+          {% if theme_display_version %}
+            {%- set nav_version = version %}
+            {% if READTHEDOCS and current_version %}
+              {%- set nav_version = current_version %}
+            {% endif %}
+            {% if nav_version %}
+              <div class="version">
+                {{ nav_version }}
+              </div>
+            {% endif %}
+          {% endif %}
+
+          {% include "searchbox.html" %}
+
+          {% endblock %}
+        </div>
+
+        <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
+          {% block menu %}
+            {% set toctree = toctree(maxdepth=4, collapse=theme_collapse_navigation, includehidden=True) %}
+            {% if toctree %}
+                {{ toctree }}
+            {% else %}
+                <!-- Local TOC -->
+                <div class="local-toc">{{ toc }}</div>
+            {% endif %}
+          {% endblock %}
+        </div>
       </div>
-      &nbsp;
     </nav>
 
     <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">

sphinx_rtd_theme/static/js/theme.js

@@ -75,7 +75,7 @@ window.SphinxRtdTheme = (function (jquery) {
                 resize();
             },
             init = function () {
-                navBar = jquery('nav.wy-nav-side:first');
+                navBar = jquery('div.wy-side-scroll:first');
                 win = jquery(window);
             },
             reset = function () {