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 openedpython/cpython#116966 andpython/cpython#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 inhttps://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?

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 frommain branch and changes made to that versions file will be reflected in the documentation built from a PR.

My 0.02€ 😄

Some initial thoughts:

As@humitos mentioned, we've already made a start on prep for RTD hosting and the selectors athttps://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 athttps://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 ashttps://typing.readthedocs.io, so things like this should be opt-in.

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 usinghttps://github.com/python/devguide/blob/main/include/release-cycle.json for the versions list ...

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

• Provide the status of Python branches and versions as a csv devguide#883 (where a machine-parsable list of branches was request)
• Replace the "Status of the Python branches" table with a csv. devguide#884 (which added it as a CSV)
• Generate release cycle chart and CSV devguide#988 (which converted it to a JSON)

andhttps://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 fromrelease-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.

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 onpython/docs-community#5 (comment) 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 😄

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 usingpython/devguide@main/include/release-cycle.json for the versions list andpython/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.

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 thecpython repository itself, maybe underDoc/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 theDoc/ folder in the CPython repository.

This is a good point to me as well 👍🏼 . What about adding these JSON files (available versions and languages) in thecpython repository itself, maybe underDoc/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 onlymain counts, and we fetch the file directly from a staticmain 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).

All commit authors signed the Contributor License Agreement.