Skip to content
Permalink
Browse files

Doc: Backport language switcher (bpo-33700, bpo-31045) (#8048)

  • Loading branch information...
JulienPalard authored and larryhastings committed Jul 2, 2018
1 parent 13402fc commit 1b141b9553424971639bde281feb1d4e4e586dbe
Showing with 160 additions and 74 deletions.
  1. +2 −2 Doc/Makefile
  2. +8 −4 Doc/conf.py
  3. +147 −0 Doc/tools/static/switchers.js
  4. +0 −66 Doc/tools/static/version_switch.js
  5. +3 −2 Doc/tools/templates/layout.html
@@ -184,12 +184,12 @@ serve:

# for development releases: always build
autobuild-dev:
make dist SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1 -A versionswitcher=1'
make dist SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1 -A switcher=1'
-make suspicious

# for quick rebuilds (HTML only)
autobuild-dev-html:
make html SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1 -A versionswitcher=1'
make html SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1 -A switcher=1'

# for stable releases: only build if not in pre-release stage (alpha, beta)
# release candidate downloads are okay, since the stable tree can be in that stage
@@ -90,13 +90,17 @@
# ------------------------

# Get LaTeX to handle Unicode correctly
latex_elements = {'inputenc': r'\usepackage[utf8x]{inputenc}', 'utf8extra': ''}
latex_elements = {
'inputenc': r'\usepackage[utf8x]{inputenc}',
'utf8extra': '',
'fontenc': r'\usepackage[T1,T2A]{fontenc}',
}

# Additional stuff for the LaTeX preamble.
latex_elements['preamble'] = r'''
\authoraddress{
\strong{Python Software Foundation}\\
Email: \email{docs@python.org}
\sphinxstrong{Python Software Foundation}\\
Email: \sphinxemail{docs@python.org}
}
\let\Verbatim=\OriginalVerbatim
\let\endVerbatim=\endOriginalVerbatim
@@ -106,7 +110,7 @@
latex_elements['papersize'] = 'a4'

# The font size ('10pt', '11pt' or '12pt').
latex_elements['font_size'] = '10pt'
latex_elements['pointsize'] = '10pt'

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, document class [howto/manual]).
@@ -0,0 +1,147 @@
(function() {
'use strict';

// Parses versions in URL segments like:
// "3", "dev", "release/2.7" or "3.6rc2"
var version_regexs = [
'(?:\\d)',
'(?:\\d\\.\\d[\\w\\d\\.]*)',
'(?:dev)',
'(?:release/\\d.\\d[\\x\\d\\.]*)'];

var all_versions = {
'3.8': 'dev (3.8)',
'3.7': '3.7',
'3.6': '3.6',
'3.5': '3.5',
'2.7': '2.7',
};

var all_languages = {
'en': 'English',
'fr': 'French',
'ja': 'Japanese',
'ko': 'Korean',
};

function build_version_select(current_version, current_release) {
var buf = ['<select>'];

$.each(all_versions, function(version, title) {
buf.push('<option value="' + version + '"');
if (version == current_version)
buf.push(' selected="selected">' + current_release + '</option>');
else
buf.push('>' + title + '</option>');
});

buf.push('</select>');
return buf.join('');
}

function build_language_select(current_language) {
var buf = ['<select>'];

$.each(all_languages, function(language, title) {
if (language == current_language)
buf.push('<option value="' + language + '" selected="selected">' +
all_languages[current_language] + '</option>');
else
buf.push('<option value="' + language + '">' + title + '</option>');
});
buf.push('</select>');
return buf.join('');
}

function navigate_to_first_existing(urls) {
// Navigate to the first existing URL in urls.
var url = urls.shift();
if (urls.length == 0) {
window.location.href = url;
return;
}
$.ajax({
url: url,
success: function() {
window.location.href = url;
},
error: function() {
navigate_to_first_existing(urls);
}
});
}

function on_version_switch() {
var selected_version = $(this).children('option:selected').attr('value') + '/';
var url = window.location.href;
var current_language = language_segment_from_url(url);
var current_version = version_segment_in_url(url);
var new_url = url.replace('.org/' + current_language + current_version,
'.org/' + current_language + selected_version);
if (new_url != url) {
navigate_to_first_existing([
new_url,
url.replace('.org/' + current_language + current_version,
'.org/' + selected_version),
'https://docs.python.org/' + current_language + selected_version,
'https://docs.python.org/' + selected_version,
'https://docs.python.org/'
]);
}
}

function on_language_switch() {
var selected_language = $(this).children('option:selected').attr('value') + '/';
var url = window.location.href;
var current_language = language_segment_from_url(url);
var current_version = version_segment_in_url(url);
if (selected_language == 'en/') // Special 'default' case for english.
selected_language = '';
var new_url = url.replace('.org/' + current_language + current_version,
'.org/' + selected_language + current_version);
if (new_url != url) {
navigate_to_first_existing([
new_url,
'https://docs.python.org/'
]);
}
}

// Returns the path segment of the language as a string, like 'fr/'
// or '' if not found.
function language_segment_from_url(url) {
var language_regexp = '\.org/([a-z]{2}(?:-[a-z]{2})?/)';
var match = url.match(language_regexp);
if (match !== null)
return match[1];
return '';
}

// Returns the path segment of the version as a string, like '3.6/'
// or '' if not found.
function version_segment_in_url(url) {
var language_segment = '(?:[a-z]{2}(?:-[a-z]{2})?/)';
var version_segment = '(?:(?:' + version_regexs.join('|') + ')/)';
var version_regexp = '\\.org/' + language_segment + '?(' + version_segment + ')';
var match = url.match(version_regexp);
if (match !== null)
return match[1];
return ''
}

$(document).ready(function() {
var release = DOCUMENTATION_OPTIONS.VERSION;
var language_segment = language_segment_from_url(window.location.href);
var current_language = language_segment.replace(/\/+$/g, '') || 'en';
var version = release.substr(0, 3);
var version_select = build_version_select(version, release);

$('.version_switcher_placeholder').html(version_select);
$('.version_switcher_placeholder select').bind('change', on_version_switch);

var language_select = build_language_select(current_language);

$('.language_switcher_placeholder').html(language_select);
$('.language_switcher_placeholder select').bind('change', on_language_switch);
});
})();

This file was deleted.

@@ -4,7 +4,8 @@
style="vertical-align: middle; margin-top: -1px"/></li>
<li><a href="https://www.python.org/">Python</a>{{ reldelim1 }}</li>
<li>
{%- if versionswitcher is defined %}
{%- if switchers is defined %}
<span class="language_switcher_placeholder">{{ language or 'en' }}</span>
<span class="version_switcher_placeholder">{{ release }}</span>
<a href="{{ pathto('index') }}">{% trans %}Documentation {% endtrans %}</a>{{ reldelim1 }}
{%- else %}
@@ -41,7 +42,7 @@
<link rel="canonical" href="https://docs.python.org/3/{{pagename}}.html" />
{% if builder != "htmlhelp" %}
{% if not embedded %}<script type="text/javascript" src="{{ pathto('_static/copybutton.js', 1) }}"></script>{% endif %}
{% if versionswitcher is defined and not embedded %}<script type="text/javascript" src="{{ pathto('_static/version_switch.js', 1) }}"></script>{% endif %}
{% if switchers is defined and not embedded %}<script type="text/javascript" src="{{ pathto('_static/switchers.js', 1) }}"></script>{% endif %}
{% if pagename == 'whatsnew/changelog' and not embedded %}
<script type="text/javascript">
$(document).ready(function() {

0 comments on commit 1b141b9

Please sign in to comment.
You can’t perform that action at this time.