Refactor switchers.js

[AA-Turner]

• Modernise (remove obsolete polyfills, update to use e.g. arrow functions, use Map over object literals)
• Improve documentation (add JSDoc comments)
• Improve handling for local browsing (file: URIs)
• Improve core redirection logic
• Improve readability (prefer named functions to anonymous, give more variables names)
• Create switchers from DOM nodes rather than less-secure parsing of HTML strings

A

[ezio-melotti]

I haven't checked everything in detail, but what I saw LGTM.

[hugovk]

Not related to this PR, but I read through PEP 545 – Python Documentation Translations this weekend and it says:

http://docs.python.org/en/ will redirect to http://docs.python.org/.

Currently /en/ is 404, I wonder if we should add this redirect or if it was decided to be unnecessary?

[AA-Turner]

I've also seen that, though I never got around to updating the PEP. I think that we should remove it from the PEP as something that was never implemented, rather than adding another set of redirects to maintain.

[hugovk]

I don't know how many people try /en/, but fine by me. And the PEP should probably Process/Active rather than Process/Final.

[hugovk]

See python/peps#4093

[hugovk]

I'm wondering if it would be better to stick in the current language, even if that means going back to the homepage?

It might be surprising to switch to a completely different language set; as you navigate further everything is English and not your chosen language.

And I think different languages should nearly always have the same structure and same pages for any given version? (Although with some untranslated pages.)

That would mean:

Suggested change

	// 1. The current page in the current language with the new version
	// 2. The current page in English with the new version
	// 3. The documentation home in the current language with the new version
	// 4. The documentation home in English with the new version
	_navigate_to_first_existing([
	window.location.href.replace(_CURRENT_PREFIX, new_prefix),
	window.location.href.replace(_CURRENT_PREFIX, new_prefix_en),
	new_prefix,
	new_prefix_en,
	// 1. The current page in the current language with the new version
	// 2. The documentation home in the current language with the new version
	// 3. The current page in English with the new version
	// 4. The documentation home in English with the new version
	_navigate_to_first_existing([
	window.location.href.replace(_CURRENT_PREFIX, new_prefix),
	new_prefix,
	window.location.href.replace(_CURRENT_PREFIX, new_prefix_en),
	new_prefix_en,

But I'm really not sure. Might be worth asking people who regularly uses the docs in another language?

[AA-Turner]

Shall we create an issue for this? The intent in this PR was for as few behavioural changes as possible (the ideally none!).

Although, the current order does have some logic, given that a reader probably prefers to have the information (which can be translated via browser tools, Google, etc) rather than always being sent to the homepage for a language that doesn't have much translation coverage.

(Also, this order was chosen by a French-speaker!)

A

[hugovk]

I asked in the Docs Discord: https://discord.com/channels/935215565872693329/935215566334079058/1300710927531905084

[AA-Turner]

I'll merge this tomorrow so that I can keep an eye on builds (unless anyone would prefer we delay)

A

[hugovk]

I'll merge this tomorrow so that I can keep an eye on builds (unless anyone would prefer we delay)

A

That's fine, we can easily adjust the order later if needed. Thanks!

[AA-Turner]

Force-push diff (added logging for _navigate_to_first_existing)

[hugovk]

I just noticed, likely this PR has resulted in this bit of CSS no longer applying for smaller screens:

@media (max-width: 1023px) {
    .version_switcher_placeholder > select {
        height: 100%;
    }
}

And so the version switcher (in 3.12-3.14) doesn't fill the top bar:

[AA-Turner]

#233 to fix.