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

从提议的根级 versions.js API 和 issue 中引用的 docsbuild-scripts build_docs.py switcher 代码开始；比较链接中的方法和现有的 GitHub Action artifact workflow。Done 应该是一个已确定且可在本地测试的 switcher 设置，但 issue 没有定义具体的实现或验收标准。