[docs] Add a version switcher to python docs site (issue 16331)

yselivanov.ml at gmail.com yselivanov.ml at gmail.com
Fri Oct 26 19:53:25 CEST 2012


Reviewers: ezio.melotti,


http://bugs.python.org/review/16331/diff/6400/Doc/conf.py
File Doc/conf.py (right):

http://bugs.python.org/review/16331/diff/6400/Doc/conf.py#newcode72
Doc/conf.py:72: html_short_title = 'Documentation'
On 2012/10/26 19:48:52, ezio.melotti wrote:
> I would leave this unchanged, in order to have the right title when js
is not
> available.

Eric,

If JS is not available, then '''<span id="version_switcher">''' will
contain the release number, hence, for the user it will look like docs
without this patch applied.



Please review this at http://bugs.python.org/review/16331/

Affected files:
  Doc/conf.py
  Doc/tools/sphinxext/layout.html
  Doc/tools/sphinxext/static/version_switch.js


diff --git a/Doc/conf.py b/Doc/conf.py
index 6b085e0..b9eb9f4 100644
--- a/Doc/conf.py
+++ b/Doc/conf.py
@@ -69,7 +69,7 @@ html_theme = 'pydoctheme'
 html_theme_path = ['tools/sphinxext']
 html_theme_options = {'collapsiblesidebar': True}
 
-html_short_title = '%s Documentation' % release
+html_short_title = 'Documentation'
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
diff --git a/Doc/tools/sphinxext/layout.html b/Doc/tools/sphinxext/layout.html
index 3f68a00..bebb0a4 100644
--- a/Doc/tools/sphinxext/layout.html
+++ b/Doc/tools/sphinxext/layout.html
@@ -3,11 +3,17 @@
         <li><img src="{{ pathto('_static/py.png', 1) }}" alt=""
                  style="vertical-align: middle; margin-top: -1px"/></li>
         <li><a href="http://www.python.org/">Python</a>{{ reldelim1 }}</li>
-        <li><a href="{{ pathto('index') }}">{{ shorttitle }}</a>{{ reldelim1 }}</li>
+        <li>
+            <span id="version_switcher">{{ release }}</span>
+            <a href="{{ pathto('index') }}">{{ shorttitle }}</a>{{ reldelim1 }}
+        </li>
 {% endblock %}
 {% block extrahead %}
     <link rel="shortcut icon" type="image/png" href="{{ pathto('_static/py.png', 1) }}" />
-    {% if not embedded %}<script type="text/javascript" src="{{ pathto('_static/copybutton.js', 1) }}"></script>{% endif %}
+    {% if not embedded %}
+        <script type="text/javascript" src="{{ pathto('_static/copybutton.js', 1) }}"></script>
+        <script type="text/javascript" src="{{ pathto('_static/version_switch.js', 1) }}"></script>
+    {% endif %}
     {% if pagename == 'whatsnew/changelog' %}
     <script type="text/javascript">
       $(document).ready(function() {
diff --git a/Doc/tools/sphinxext/static/version_switch.js b/Doc/tools/sphinxext/static/version_switch.js
new file mode 100644
index 0000000..ea5a4eb
--- /dev/null
+++ b/Doc/tools/sphinxext/static/version_switch.js
@@ -0,0 +1,87 @@
+(function() {
+    'use strict';
+
+    var all_versions = ['3.4', '3.3', '3.2', '3.1', '3.0',
+                        '2.7', '2.6', '2.5', '2.4', '2.3', '2.2', '2.1', '2.0'];
+
+    function get_version(release) {
+        var split = release.split('.');
+        return split[0] + '.' + split[1];
+    }
+
+    function get_doc_versions(current_release) {
+        var version = get_version(current_release),
+            doc_versions = {};
+
+        $.each(all_versions, function(i, v) {
+            doc_versions[v] = {
+                title: v
+            };
+        });
+
+        doc_versions[version].title = current_release;
+        doc_versions[version].selected = true;
+
+        return doc_versions;
+    }
+
+    function build_select(current_release) {
+        var doc_versions = get_doc_versions(current_release),
+            buf = ['<select>'];
+
+        $.each(doc_versions, function(version, config) {
+            buf.push('<option value="' + version + '"');
+            if (config.selected) {
+                buf.push(' selected="selected"');
+            }
+            buf.push('>' + config.title + '</option>');
+        });
+
+        buf.push('</select>');
+
+        return buf.join('');
+    }
+
+    function patch_url(url, new_version) {
+        var url_re = /\.org\/(py3k|release\/\d\.\d[\w\d\.]*|\d\.\d[\w\d\.]*)\//,
+            new_url = url.replace(url_re,
+                                  '.org/' + new_version + '/');
+
+        if (new_url == url && !new_url.match(url_re)) {
+            // python 2 url without version?
+            new_url = url.replace(/\.org\//, '.org/' + new_version + '/');
+        }
+
+        return new_url;
+    }
+
+    function on_switch() {
+        var selected = null;
+
+        $('#version_switcher option').each(function(index, el) {
+            if (el.selected) {
+                selected = el.value;
+            }
+        });
+
+        var url = window.location.href,
+            new_url = patch_url(url, selected);
+
+        if (new_url != url) {
+            $.get(new_url, function() {
+                // url exists
+                window.location.href = new_url;
+            }).error(function() {
+                window.location.href = 'http://docs.python.org/' + selected;
+            });
+        }
+    }
+
+    $(document).ready(function() {
+        var release = $('#version_switcher').html();
+
+        $('#version_switcher')
+            .html(build_select(release))
+            .bind('change', on_switch);
+    });
+})();




More information about the docs mailing list