Enhancing the switchers setup

Currently the contributions to python-docs-theme are made hard because of the language and version switchers.

I made review a bit easier by adding a github action to build the doc and provide it as a built artifact, so reviewers can just download and test locally.

But still the enhancement of the doc is made hard, for example https://github.com/python/python-docs-theme/pull/46 has been slowed down because of this (sry @obulat).

Solution 1

I once had an idea to enhance the situation: we could provide an "API" on the form of a simple .js file at the root of docs.python.org listing the available versions and languages.

pros:

• It removes the switchers ugly hack in docsbuild-scripts.
• It make the theme easy to test locally: just drop a versions.js at the root with some sample data.
• A project using our theme with no need for switchers will not use a version.js file and have no switchers.
• A project using our theme with the need for switchers could set them up easily (add a version.js file).

cons:

• This is already the case, but we should be aware of the SEO penality that we could have if we redrow the page after load to render the switchers.
• The impementation will probably be tied to our specific hiearchy: /{LANG}/{VERSION}/ with the language being optional, defaulting to english.
• It may not follow the current state of the art of doing this, as I did not reviewd how other themes do this, how readthedocs does it, how for example https://docs.djangoproject.com/en/3.1/ does it.

Other ideas, and feedback welcome.

cc @pradyunsg @obulat

Bắt đầu với API versions.js được đề xuất ở cấp root và mã switcher trong docsbuild-scripts build_docs.py được tham chiếu trong issue; so sánh các cách tiếp cận được liên kết và workflow artifact GitHub Action hiện có. Done nên là một thiết lập switcher đã được quyết định và có thể kiểm thử cục bộ, nhưng issue không xác định một triển khai cụ thể hoặc tiêu chí chấp nhận.