Skip to content

Commit 1b141b9

Browse files
JulienPalardlarryhastings
authored andcommitted
Doc: Backport language switcher (bpo-33700, bpo-31045) (#8048)
1 parent 13402fc commit 1b141b9

File tree

5 files changed

+160
-74
lines changed

5 files changed

+160
-74
lines changed

Doc/Makefile

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -184,12 +184,12 @@ serve:
184184

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

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

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

Doc/conf.py

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -90,13 +90,17 @@
9090
# ------------------------
9191

9292
# Get LaTeX to handle Unicode correctly
93-
latex_elements = {'inputenc': r'\usepackage[utf8x]{inputenc}', 'utf8extra': ''}
93+
latex_elements = {
94+
'inputenc': r'\usepackage[utf8x]{inputenc}',
95+
'utf8extra': '',
96+
'fontenc': r'\usepackage[T1,T2A]{fontenc}',
97+
}
9498

9599
# Additional stuff for the LaTeX preamble.
96100
latex_elements['preamble'] = r'''
97101
\authoraddress{
98-
\strong{Python Software Foundation}\\
99-
Email: \email{[email protected]}
102+
\sphinxstrong{Python Software Foundation}\\
103+
Email: \sphinxemail{[email protected]}
100104
}
101105
\let\Verbatim=\OriginalVerbatim
102106
\let\endVerbatim=\endOriginalVerbatim
@@ -106,7 +110,7 @@
106110
latex_elements['papersize'] = 'a4'
107111

108112
# The font size ('10pt', '11pt' or '12pt').
109-
latex_elements['font_size'] = '10pt'
113+
latex_elements['pointsize'] = '10pt'
110114

111115
# Grouping the document tree into LaTeX files. List of tuples
112116
# (source start file, target name, title, author, document class [howto/manual]).

Doc/tools/static/switchers.js

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
(function() {
2+
'use strict';
3+
4+
// Parses versions in URL segments like:
5+
// "3", "dev", "release/2.7" or "3.6rc2"
6+
var version_regexs = [
7+
'(?:\\d)',
8+
'(?:\\d\\.\\d[\\w\\d\\.]*)',
9+
'(?:dev)',
10+
'(?:release/\\d.\\d[\\x\\d\\.]*)'];
11+
12+
var all_versions = {
13+
'3.8': 'dev (3.8)',
14+
'3.7': '3.7',
15+
'3.6': '3.6',
16+
'3.5': '3.5',
17+
'2.7': '2.7',
18+
};
19+
20+
var all_languages = {
21+
'en': 'English',
22+
'fr': 'French',
23+
'ja': 'Japanese',
24+
'ko': 'Korean',
25+
};
26+
27+
function build_version_select(current_version, current_release) {
28+
var buf = ['<select>'];
29+
30+
$.each(all_versions, function(version, title) {
31+
buf.push('<option value="' + version + '"');
32+
if (version == current_version)
33+
buf.push(' selected="selected">' + current_release + '</option>');
34+
else
35+
buf.push('>' + title + '</option>');
36+
});
37+
38+
buf.push('</select>');
39+
return buf.join('');
40+
}
41+
42+
function build_language_select(current_language) {
43+
var buf = ['<select>'];
44+
45+
$.each(all_languages, function(language, title) {
46+
if (language == current_language)
47+
buf.push('<option value="' + language + '" selected="selected">' +
48+
all_languages[current_language] + '</option>');
49+
else
50+
buf.push('<option value="' + language + '">' + title + '</option>');
51+
});
52+
buf.push('</select>');
53+
return buf.join('');
54+
}
55+
56+
function navigate_to_first_existing(urls) {
57+
// Navigate to the first existing URL in urls.
58+
var url = urls.shift();
59+
if (urls.length == 0) {
60+
window.location.href = url;
61+
return;
62+
}
63+
$.ajax({
64+
url: url,
65+
success: function() {
66+
window.location.href = url;
67+
},
68+
error: function() {
69+
navigate_to_first_existing(urls);
70+
}
71+
});
72+
}
73+
74+
function on_version_switch() {
75+
var selected_version = $(this).children('option:selected').attr('value') + '/';
76+
var url = window.location.href;
77+
var current_language = language_segment_from_url(url);
78+
var current_version = version_segment_in_url(url);
79+
var new_url = url.replace('.org/' + current_language + current_version,
80+
'.org/' + current_language + selected_version);
81+
if (new_url != url) {
82+
navigate_to_first_existing([
83+
new_url,
84+
url.replace('.org/' + current_language + current_version,
85+
'.org/' + selected_version),
86+
'https://docs.python.org/' + current_language + selected_version,
87+
'https://docs.python.org/' + selected_version,
88+
'https://docs.python.org/'
89+
]);
90+
}
91+
}
92+
93+
function on_language_switch() {
94+
var selected_language = $(this).children('option:selected').attr('value') + '/';
95+
var url = window.location.href;
96+
var current_language = language_segment_from_url(url);
97+
var current_version = version_segment_in_url(url);
98+
if (selected_language == 'en/') // Special 'default' case for english.
99+
selected_language = '';
100+
var new_url = url.replace('.org/' + current_language + current_version,
101+
'.org/' + selected_language + current_version);
102+
if (new_url != url) {
103+
navigate_to_first_existing([
104+
new_url,
105+
'https://docs.python.org/'
106+
]);
107+
}
108+
}
109+
110+
// Returns the path segment of the language as a string, like 'fr/'
111+
// or '' if not found.
112+
function language_segment_from_url(url) {
113+
var language_regexp = '\.org/([a-z]{2}(?:-[a-z]{2})?/)';
114+
var match = url.match(language_regexp);
115+
if (match !== null)
116+
return match[1];
117+
return '';
118+
}
119+
120+
// Returns the path segment of the version as a string, like '3.6/'
121+
// or '' if not found.
122+
function version_segment_in_url(url) {
123+
var language_segment = '(?:[a-z]{2}(?:-[a-z]{2})?/)';
124+
var version_segment = '(?:(?:' + version_regexs.join('|') + ')/)';
125+
var version_regexp = '\\.org/' + language_segment + '?(' + version_segment + ')';
126+
var match = url.match(version_regexp);
127+
if (match !== null)
128+
return match[1];
129+
return ''
130+
}
131+
132+
$(document).ready(function() {
133+
var release = DOCUMENTATION_OPTIONS.VERSION;
134+
var language_segment = language_segment_from_url(window.location.href);
135+
var current_language = language_segment.replace(/\/+$/g, '') || 'en';
136+
var version = release.substr(0, 3);
137+
var version_select = build_version_select(version, release);
138+
139+
$('.version_switcher_placeholder').html(version_select);
140+
$('.version_switcher_placeholder select').bind('change', on_version_switch);
141+
142+
var language_select = build_language_select(current_language);
143+
144+
$('.language_switcher_placeholder').html(language_select);
145+
$('.language_switcher_placeholder select').bind('change', on_language_switch);
146+
});
147+
})();

Doc/tools/static/version_switch.js

Lines changed: 0 additions & 66 deletions
This file was deleted.

Doc/tools/templates/layout.html

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@
44
style="vertical-align: middle; margin-top: -1px"/></li>
55
<li><a href="https://www.python.org/">Python</a>{{ reldelim1 }}</li>
66
<li>
7-
{%- if versionswitcher is defined %}
7+
{%- if switchers is defined %}
8+
<span class="language_switcher_placeholder">{{ language or 'en' }}</span>
89
<span class="version_switcher_placeholder">{{ release }}</span>
910
<a href="{{ pathto('index') }}">{% trans %}Documentation {% endtrans %}</a>{{ reldelim1 }}
1011
{%- else %}
@@ -41,7 +42,7 @@
4142
<link rel="canonical" href="https://docs.python.org/3/{{pagename}}.html" />
4243
{% if builder != "htmlhelp" %}
4344
{% if not embedded %}<script type="text/javascript" src="{{ pathto('_static/copybutton.js', 1) }}"></script>{% endif %}
44-
{% if versionswitcher is defined and not embedded %}<script type="text/javascript" src="{{ pathto('_static/version_switch.js', 1) }}"></script>{% endif %}
45+
{% if switchers is defined and not embedded %}<script type="text/javascript" src="{{ pathto('_static/switchers.js', 1) }}"></script>{% endif %}
4546
{% if pagename == 'whatsnew/changelog' and not embedded %}
4647
<script type="text/javascript">
4748
$(document).ready(function() {

0 commit comments

Comments
 (0)