Add a version selector dropdown to the main menu

This adds a version selection dropdown to the menu. It is used to redirect on
change to the version URL. The ``versions`` theme option is added and is used to
add a mapping of version slugs to URLs.

Currently, this is going to be used in pydoc.io. The implementation will change
the javascript slightly, to accept json data instead of a blob of HTML.

This will currently be disabled on Read the Docs, as we are rethinking what the
version selection menu looks like.

Author: agjohnson

README.rst

@@ -13,7 +13,7 @@
 Read the Docs Sphinx Theme
 **************************
 
-.. contents:: 
+.. contents::
 
 View a working demo_ over on readthedocs.org_.
 
@@ -82,23 +82,43 @@ file of this repository, and can be defined in your project's ``conf.py`` via
         'collapse_navigation': False,
         'display_version': False,
         'navigation_depth': 3,
+        'versions': {
+            '1.0': 'https://example.com/1.0/',
+            '2.0': 'https://example.com/2.0/',
+        }
     }
 
 The following options are available:
 
-* ``canonical_url`` This will specify a `canonical url <https://en.wikipedia.org/wiki/Canonical_link_element>`__
-  to let search engines know they should give higher ranking to latest version of the docs.
-  The url points to the root of the documentation and requires a trailing slash.
+``canonical_url``
+    This will specify a `canonical url
+    <https://en.wikipedia.org/wiki/Canonical_link_element>`__ to let search
+    engines know they should give higher ranking to latest version of the
+    docs. The url points to the root of the documentation and requires a
+    trailing slash.
+
+``versions``
+    This option should be defined as a dictionary of versions, where the key
+    is the version slug and the value is the URL. This will enable a version
+    dropdown at the top of the menu.
+
+    .. note::
+        This is disabled on Read the Docs currently
 
 Page-level configuration
 ------------------------
 
 Pages support metadata that changes how the theme renders.
 You can currently add the following:
 
-* ``:github_url:`` This will force the "Edit on GitHub" to the configured URL
-* ``:bitbucket_url:`` This will force the "Edit on Bitbucket" to the configured URL
-* ``:gitlab_url:`` This will force the "Edit on GitLab" to the configured URL
+``:github_url:``
+    This will force the "Edit on GitHub" to the configured URL
+
+``:bitbucket_url:``
+    This will force the "Edit on Bitbucket" to the configured URL
+
+``:gitlab_url:``
+    This will force the "Edit on GitLab" to the configured URL
 
 Changelog
 =========
@@ -119,6 +139,7 @@ master
 * Fix padding on field lists
 * Add setuptools entry point allowing to use ``sphinx_rtd_theme`` as
   Sphinx ``html_theme`` directly.
+* Add version dropdown select
 
 v0.2.4
 ------

demo_docs/source/conf.py

@@ -111,6 +111,11 @@
 html_theme_options = {
     # 'sticky_navigation': True  # Set to False to disable the sticky nav while scrolling.
     # 'logo_only': True,  # if we have a html_logo below, this shows /only/ the logo with no title text
+    'versions': {
+        '1.0': '',
+        '2.0': '',
+        '2.1-beta-with-a-long-name': '',
+    }
 }
 
 # Add any paths that contain custom themes here, relative to this directory.

js/theme.js

@@ -88,6 +88,11 @@ function ThemeNav () {
             });
             link.prepend(expand);
         });
+
+        // Add version selection URL change
+        $('#version-list').on('change', function () {
+            self.onVersionChange(this.value);
+        });
     };
 
     nav.reset = function () {
@@ -141,6 +146,10 @@ function ThemeNav () {
         this.docHeight = $(document).height();
     };
 
+    nav.onVersionChange = function (url) {
+        this.win[0].location = url;
+    };
+
     nav.hashChange = function () {
         this.linkScroll = true;
         this.win.one('hashchange', function () {

sass/_theme_layout.sass

@@ -197,7 +197,7 @@
     padding: $base-line-height / 6 $base-line-height / 4
     margin-bottom: $gutter / 2
     +font-smooth
-    &:hover
+    &:hover, &:active, &:focus
       background: rgba(255,255,255,.1)
     img.logo
       display: block  // display on its own line all the time
@@ -214,8 +214,44 @@
     margin-top: -1 * ($gutter / 4)
     margin-bottom: $gutter / 2
     font-weight: normal
-    color: rgba(255,255,255,.3)
-
+    color: rgba(255, 255, 255, .3)
+    > div.version-dropdown
+      position: relative
+      display: inline-block
+      > select
+        max-width: 8em
+        padding: .1em 1.5em .1em .5em
+        text-align-last: center
+        background: none
+        border: none
+        border-radius: 0em
+        box-shadow: none
+        font-family: $base-font-family
+        font-size: 1em
+        font-weight: normal
+        color: rgba(255, 255, 255, .3)
+        // Allow for padding
+        appearance: none
+        -webkit-appearance: none
+        -moz-appearance: none
+        &:hover, &:active, &:focus
+          background: rgba(255, 255, 255, .1)
+          color: rgba(255, 255, 255, .5)
+      &:after
+        content: "\f0d7"
+        font-size: 1em
+        line-height: 1.2em
+        font-family: FontAwesome
+        padding: .1em .5em
+        position: absolute
+        right: 0
+        top: 0
+        z-index: 1
+        text-align: center
+        width: 1.5em
+        height: 100%
+        pointer-events: none
+        box-sizing: border-box
 
 .wy-nav .wy-menu-vertical
   header

sphinx_rtd_theme/layout.html

@@ -113,7 +113,20 @@
             {% endif %}
             {% if nav_version %}
               <div class="version">
-                {{ nav_version }}
+                {% if not READTHEDOCS and theme_versions|length > 1 %}
+                  <div class="version-dropdown">
+                    <select class="version-list" id="version-list">
+                      <option value=''>{{ nav_version }}</option>
+                      {% for key, val in theme_versions.items() %}
+                        {% if key != nav_version %}
+                          <option value="{{ val }}">{{ key }}</option>
+                        {% endif %}
+                      {% endfor %}
+                    </select>
+                  </div>
+                {% else %}
+                  {{ nav_version }}
+                {% endif %}
               </div>
             {% endif %}
           {% endif %}