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

Inizia con l’API versions.js proposta a livello root e con il codice dello switcher di docsbuild-scripts build_docs.py indicato nell’issue; confronta gli approcci collegati e il workflow esistente degli artifact di GitHub Action. Done dovrebbe essere una configurazione dello switcher definita e testabile localmente, ma l’issue non definisce un’implementazione specifica né criteri di accettazione.