[ADD] support for a version switcher in odoo theme thing

needs beauty input

doc/README.rst

@@ -1,4 +1,4 @@
-.. orphan:: true
+:orphan:
 
 ==================
 Odoo Documentation
@@ -38,6 +38,10 @@ Sphinx Customizations
 Additional features
 -------------------
 
+* versions switcher, uses the ``canonical_root`` setting and an additional
+  ``versions`` setting which should be a space-separated list of available
+  versions. Appends the each version and page name to the root, and displays
+  a list of those links on the current page
 * canonical urls, requires a ``canonical_root`` setting value, and optionally
   a ``canonical_branch`` (default: ``master``)
 * :guilabel:`Edit on github` link in Sphinx pages if ``github_user`` and

doc/_themes/odoodoc/layout.html

@@ -33,6 +33,16 @@
     <div class="sphinxsidebarwrapper">
       {{ toctree(maxdepth=4, collapse=False, includehidden=True,
                  main_navbar=False, titles_only=False) }}
+      {% if versions %}
+        <div class="versions">
+          Documentation version: {{ version }}
+          <ul>
+            {% for name, url in versions %}
+              <li><a href="{{ url }}">{{ name }}</a></li>
+            {% endfor %}
+          </ul>
+        </div>
+      {% endif %}
       {% if github_link %}
         <p><a href="{{ github_link() }}" class="github">
           Edit on GitHub

doc/_themes/odoodoc/static/style.css

@@ -6346,34 +6346,14 @@ body {
 .sphinxsidebarwrapper > .nav li.current > .nav {
   display: block;
 }
-.sphinxsidebarwrapper > p {
-  margin: 5px 10px 10px;
-}
-.sphinxsidebarwrapper > p a {
-  font-size: 13px;
-}
-.sphinxsidebarwrapper > p a:hover {
-  text-decoration: none;
-}
-.sphinxsidebarwrapper > p a.github {
-  padding-left: 15px;
-  position: relative;
-}
-.sphinxsidebarwrapper > p a.github:before {
-  left: 0;
-  top: 1px;
-  content: '';
-  position: absolute;
-  width: 13px;
-  height: 13px;
-  background: url(github-link.png) left bottom / 13px no-repeat;
-}
-.sphinxsidebarwrapper > p a.github:hover:before {
-  background-position: left top;
-}
 /* Side navigation graphical styling */
+.sphinxsidebar {
+  z-index: 1;
+}
 .sphinxsidebarwrapper {
   width: 100%;
+  font-size: 13px;
+  z-index: 1;
   /* First level of nav */
   /* All levels of nav */
 }
@@ -6397,7 +6377,6 @@ body {
   margin-bottom: 20px;
 }
 .sphinxsidebarwrapper .nav > li > a {
-  font-size: 13px;
   font-weight: bold;
   padding-left: 20px;
 }
@@ -6476,6 +6455,76 @@ body {
 .sphinxsidebarwrapper .nav .nav .nav .nav > .active:focus > a {
   padding-left: 33px;
 }
+/* version switcher */
+.sphinxsidebarwrapper div.versions {
+  padding: 5px 10px 10px;
+  position: relative;
+  display: inline-block;
+  color: #777777;
+  cursor: pointer;
+}
+.sphinxsidebarwrapper div.versions:after {
+  font-family: "Glyphicons Halflings";
+  content: "\e072";
+  font-size: 80%;
+  padding-left: 3px;
+}
+.sphinxsidebarwrapper div.versions ul {
+  display: none;
+  list-style: none;
+  padding: 0;
+  margin: 0 0 0 -5px;
+  white-space: nowrap;
+  background-color: rgba(255, 255, 255, 0.9);
+  position: absolute;
+  top: 0;
+  left: 100%;
+}
+.sphinxsidebarwrapper div.versions ul > li {
+  display: inline-block;
+  margin-left: -1px;
+}
+.sphinxsidebarwrapper div.versions ul > li:first {
+  margin-left: 0;
+}
+.sphinxsidebarwrapper div.versions ul > li a {
+  color: #777777;
+  display: inline-block;
+  padding: 5px;
+}
+.sphinxsidebarwrapper div.versions ul > li a:hover {
+  text-decoration: none;
+  background-color: rgba(85, 85, 85, 0.07);
+}
+.sphinxsidebarwrapper div.versions:hover ul {
+  display: block;
+}
+/* github link for current document */
+.sphinxsidebarwrapper > p {
+  margin: 5px 10px 10px;
+}
+.sphinxsidebarwrapper > p a {
+  font-size: 13px;
+}
+.sphinxsidebarwrapper > p a:hover {
+  text-decoration: none;
+}
+.sphinxsidebarwrapper > p a.github {
+  padding-left: 15px;
+  position: relative;
+}
+.sphinxsidebarwrapper > p a.github:before {
+  left: 0;
+  top: 1px;
+  content: '';
+  position: absolute;
+  width: 13px;
+  height: 13px;
+  background: url(github-link.png) left bottom / 13px no-repeat;
+}
+.sphinxsidebarwrapper > p a.github:hover:before {
+  background-position: left top;
+}
 /* Show and affix the side nav when space allows it */
 @media (min-width: 992px) {
   .sphinxsidebarwrapper {

doc/_themes/odoodoc/static/style.less

@@ -155,33 +155,6 @@ body {
       display: block;
     }
   }
-
-  > p {
-    margin: 5px 10px 10px;
-    a {
-      font-size: 13px;
-      &:hover {
-        text-decoration: none;
-      }
-
-      &.github {
-        padding-left: 15px;
-        position: relative;
-        &:before {
-          left: 0;
-          top: 1px;
-          content: '';
-          position: absolute;
-          width: 13px;
-          height: 13px;
-          background: url(github-link.png) left bottom / 13px no-repeat;
-        }
-        &:hover:before {
-          background-position: left top;
-        }
-      }
-    }
-  }
 }
 
 /* Side navigation graphical styling */
@@ -192,8 +165,13 @@ body {
 @nav-current-offset: 2px;
 @nav-current: @nav-spacing - @nav-current-offset;
 
+.sphinxsidebar {
+  z-index: 1;
+}
 .sphinxsidebarwrapper {
   width: 100%;
+  font-size: 13px;
+  z-index: 1;
 
   .hidden-xs();
   .hidden-sm();
@@ -206,7 +184,6 @@ body {
   }
 
   .nav > li > a {
-    font-size: 13px;
     font-weight: bold;
     padding-left: @nav-spacing;
   }
@@ -283,6 +260,81 @@ body {
     }
   }
 }
+/* version switcher */
+.sphinxsidebarwrapper div.versions {
+  // use padding to set up a big hover target
+  padding: 5px 10px 10px;
+
+  position: relative;
+  display: inline-block;
+  color: @gray-light;
+  cursor: pointer;
+  // "▶" to the right of the current version's name
+  &:after {
+    font-family: "Glyphicons Halflings";
+    content: "\e072";
+    font-size: 80%;
+    // space out a bit from the version name
+    padding-left: 3px;
+  }
+
+  ul {
+    display: none;
+    list-style: none;
+    padding: 0;
+    margin: 0 0 0 -5px;
+    white-space: nowrap;
+    background-color: fade(@body-bg, 90%);
+
+    position: absolute;
+    top: 0;
+    left: 100%;
+    > li {
+      display: inline-block;
+      margin-left: -1px;
+      &:first { margin-left: 0;}
+      a {
+        color: @gray-light;
+        display: inline-block;
+        padding: 5px;
+        &:hover {
+          text-decoration: none;
+          background-color: fade(@gray, 7%);
+        }
+      }
+    }
+  }
+  &:hover ul {
+    display: block;
+  }
+}
+/* github link for current document */
+.sphinxsidebarwrapper > p {
+  margin: 5px 10px 10px;
+  a {
+    font-size: 13px;
+    &:hover {
+      text-decoration: none;
+    }
+
+    &.github {
+      padding-left: 15px;
+      position: relative;
+      &:before {
+        left: 0;
+        top: 1px;
+        content: '';
+        position: absolute;
+        width: 13px;
+        height: 13px;
+        background: url(github-link.png) left bottom / 13px no-repeat;
+      }
+      &:hover:before {
+        background-position: left top;
+      }
+    }
+  }
+}
 
 /* Show and affix the side nav when space allows it */
 @media (min-width: @screen-md-min) {

doc/conf.py

@@ -177,13 +177,40 @@ def setup(app):
     app.connect('html-page-context', canonicalize)
     app.add_config_value('canonical_root', None, 'env')
     app.add_config_value('canonical_branch', 'master', 'env')
+
+    app.connect('html-page-context', versionize)
+    app.add_config_value('versions', '', 'env')
+
 def canonicalize(app, pagename, templatename, context, doctree):
+    """ Adds a 'canonical' URL for the current document in the rendering
+    context. Requires the ``canonical_root`` setting being set. The canonical
+    branch is ``master`` but can be overridden using ``canonical_branch``.
+    """
     if not app.config.canonical_root:
         return
 
-    context['canonical'] = "{canonical_url}{canonical_branch}/{canonical_page}".format(
+    context['canonical'] = _build_url(
-        canonical_url=app.config.canonical_root,
+        app.config.canonical_root, app.config.canonical_branch, pagename)
-        canonical_branch=app.config.canonical_branch,
+
+def versionize(app, pagename, templatename, context, doctree):
+    """ Adds a version switcher below the menu, requires ``canonical_root``
+    and ``versions`` (an ordered, space-separated lists of all possible
+    versions).
+    """
+    if not (app.config.canonical_root and app.config.versions):
+        return
+
+    context['versions'] = [
+        (vs, _build_url(app.config.canonical_root, vs, pagename))
+        for vs in app.config.versions.split(',')
+        if vs != app.config.version
+    ]
+
+def _build_url(root, branch, pagename):
+    return "{canonical_url}{canonical_branch}/{canonical_page}".format(
+        canonical_url=root,
+        canonical_branch=branch,
         canonical_page=(pagename + '.html').replace('index.html', '')
                                            .replace('index/', ''),
     )
+

doc/git.rst

@@ -1,4 +1,4 @@
-:orphan: true
+:orphan:
 
 =============
 Bazaar to git