Add language and version switchers

[AA-Turner]

This is largely based on https://github.com/python/docsbuild-scripts/blob/main/templates/switchers.js, but with substantial modifications, because we can make full use of Sphinx and Jinja. This is one of the first steps needed so that we can explore hosting our docs on RTD, for example.

Specific comment would be appreciated on how to define the authoritative source for the list of versions and languages in the dropdowns. I am currently using https://github.com/python/devguide/blob/main/include/release-cycle.json for the versions list and https://github.com/python/docsbuild-scripts/blob/main/config.toml for the languages, and fetching both from the web on every build. Perhaps a static file in the theme would be better?

Once this is merged, we will need to update docsbuild-scripts to (conditionally) disable setup_switchers:

https://github.com/python/docsbuild-scripts/blob/213530446b083788da9dbf4ca02284b5dc9c5c5c/build_docs.py#L778-L780

A

[humitos]

Hi 👋🏼

This is one of the first steps needed so that we can explore hosting our docs on RTD, for example.

I'm not sure to understand the relation between this PR and Read the Docs hosting here. Some months ago we opened https://github.com/python/cpython/pull/116966 and https://github.com/python/cpython/pull/119541 to render these selectors properly on Read the Docs with the active languages/versions available on the Read the Docs project.

With that, we were able to build the selectors at the top left as shown in https://cpython-previews.readthedocs.io/en/main/. So, in theory, this PR shouldn't be needed for hosting on Read the Docs as far as I can tell.

Can you expand on this?

[humitos]

Specific comment would be appreciated on how to define the authoritative source for the list of versions and languages in the dropdowns

Taking a closer look at the PR, it seems these version/language selectors are going to be generated at build time. With that approach, keep in mind that each time a new version/language appears, all the versions for all the languages need to be re-built to include the new version/language in the selector as well.

Also, in case using a raw GitHub URL like that, it would be good adding the branch/tag this is building from. That would make the whole build to be independent from main branch and changes made to that versions file will be reflected in the documentation built from a PR.

My 0.02€ 😄

[hugovk]

Some initial thoughts:

As @humitos mentioned, we've already made a start on prep for RTD hosting and the selectors at https://cpython-previews.readthedocs.io/en/main/ are showing the languages/versions which are already on RTD: 3.11, 3.12, 3.13, main; and Spanish.

It's using RTD API to check the versions/languages associated with the RTD site.

Looking at https://docs.python.org, the version selector goes all the way back to 2.6. We will want these in the selector, but it's I doubt it's worth adding all the legacy versions to RTD, it might be tricky to get them to rebuild at this date, and they're rarely or never updated.

And similarly for languages, we'll still want to link to the existing ones before importing them to RTD.

So I think we'll need something to define which language/versions are on RTD, and which are not?

---

Also, this theme is also used by non-docs.python.org sites, such as https://typing.readthedocs.io, so things like this should be opt-in.

[ezio-melotti]

Specific comment would be appreciated on how to define the authoritative source for the list of versions and languages in the dropdowns. I am currently using https://github.com/python/devguide/blob/main/include/release-cycle.json for the versions list ...

FWIW, release-cycle.json is meant to be the SSOT for the release -- see:

• https://github.com/python/devguide/pull/883 (where a machine-parsable list of branches was request)
• https://github.com/python/devguide/pull/884 (which added it as a CSV)
• https://github.com/python/devguide/pull/988 (which converted it to a JSON)

and https://github.com/python/docsbuild-scripts/blob/main/config.toml for the languages, and fetching both from the web on every build. Perhaps a static file in the theme would be better?

If you want to create a static file, it should be generated automatically from release-cycle.json rather than duplicating its content in a new file that needs to be maintained manually.

I'm not familiar with the language list, but the same idea applies there too.

[humitos]

After re-reading some threads related to the switchers, digging into the code and clarifying some doubts that I had regarding the current build process, I commented on https://github.com/python/docs-community/issues/5#issuecomment-2245590647 with migration proposal for hosting the documentation on Read the Docs. I just wanted to comment here as well since is strictly related to this PR. Let me know your thoughts 😄

[hugovk]

Yep, that looks like a good plan.

Specific comment would be appreciated on how to define the authoritative source for the list of versions and languages in the dropdowns. I am currently using python/devguide@main/include/release-cycle.json for the versions list and python/docsbuild-scripts@main/config.toml for the languages, and fetching both from the web on every build. Perhaps a static file in the theme would be better?

I think the JSON file is better than a static file in the theme, as @ezio-melotti pointed out, it's a single source of truth for releases.

About listing languages, perhaps we should also put them in the JSON?

One negative point for putting things in the docsbuild-scripts repo: I think core devs by default don't have merge permission there. At least @AA-Turner and I don't. We don't want to be bus factored.

And docsbuild-scripts is for the old docs server setup. It could be cleaner if we keep the new RTD deploy stuff separated.

[humitos]

About listing languages, perhaps we should also put them in the JSON? One negative point for putting things in the docsbuild-scripts repo: I think core devs by default don't have merge permission there.

This is a good point to me as well 👍🏼 . What about adding these JSON files (available versions and languages) in the cpython repository itself, maybe under Doc/tools/static/.

And docsbuild-scripts is for the old docs server setup. It could be cleaner if we keep the new RTD deploy stuff separated.

This will definitely make things easier, yes. Talking from my own experience trying to understand how the documentation build process works, it was challenging to jump between CPython, docsbuild-script and the theme repository to understand what happens and where it happens.

Ideally, all the things required to build the documentation, IMHO, should be next to the code itself, under the Doc/ folder in the CPython repository.

[hugovk]

This is a good point to me as well 👍🏼 . What about adding these JSON files (available versions and languages) in the cpython repository itself, maybe under Doc/tools/static/.

One thing about CPython repo is we need to worry about the backport branches. We try not to touch the security branches (currently 3.8-3.11) and only backport to bugfix or later branches (currently 3.12-3.13).

Even if we could backport all the way to 3.8, that's 7 PRs to keep the data all in sync.

Unless we said only main counts, and we fetch the file directly from a static main URL. Downsides to this: the file will eventually end up in older branches and be out of date there, this could be a little confusing. And if we're fetching the file from a static location (main), it might be easier to have it somewhere else (like devguide or theme).

[python-cla-bot[bot]]

All commit authors signed the Contributor License Agreement.