Add language and version switchers #193
Conversation
|
Hi 👋🏼
I'm not sure to understand the relation between this PR and Read the Docs hosting here. Some months ago we opened python/cpython#116966 and python/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 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? |
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 My 0.02€ 😄 |
|
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. |
FWIW,
If you want to create a static file, it should be generated automatically from I'm not familiar with the language list, but the same idea applies there too. |
_Note this is just a proof of concept to start the conversation._ While working on the idea to generate the version/language selectors and combine them with the data fetched from Read the Docs API, I realized that if we are migrating only _one_ version to Read the Docs and using a proxy to serve it at the official `docs.python.org` domain, there is no need to use a different version/language selector at all --since all the URLs will be the same and all the JavaScript logic will be the same. The proxy will do the magic to redirect to Read the Docs _only_ the versions configured in the proxy [^1]. However, since when building on Read the Docs the variables `VERSIONS` and `LANGUAGES` are not passed, we need to populate them dynamically with JavaScript when the page is served. Do we have a JSON file from where we can populate the `LANGUAGES` variable? I'm opening a PR here to show what I'm thinking and discuss if this is the approach we want to follow. BTW, the code is not tested. I just wrote it as an example to show what I'm thinking is the direction. Related: - python/python-docs-theme#193 - python/docs-community#5 [^1]: Once all the versions/languages are migrated to Read the Docs, we won't require the `release-cycle.json` nor other file to populate the `LANGUAGES` variable because this data will come from Read the Docs Addons API.
_Note this is just a proof of concept to start the conversation._ While working on the idea to generate the version/language selectors and combine them with the data fetched from Read the Docs API, I realized that if we are migrating only _one_ version to Read the Docs and using a proxy to serve it at the official `docs.python.org` domain, there is no need to use a different version/language selector at all --since all the URLs will be the same and all the JavaScript logic will be the same. The proxy will do the magic to redirect to Read the Docs _only_ the versions configured in the proxy [^1]. However, since when building on Read the Docs the variables `VERSIONS` and `LANGUAGES` are not passed, we need to populate them dynamically with JavaScript when the page is served. - Populate `all_languages` in the same way. Do we have a JSON file from where we can populate the `LANGUAGES` variable? - Move this `switchers.js` file to https://github.com/python/cpython/tree/main/Doc/tools/static ---- I'm opening a PR here to show what I'm thinking and discuss if this is the approach we want to follow. BTW, the code is not tested. I just wrote it as an example to show what I'm thinking is the direction. Related: - python/python-docs-theme#193 - python/docs-community#5 [^1]: Once all the versions/languages are migrated to Read the Docs, we won't require the `release-cycle.json` nor other file to populate the `LANGUAGES` variable because this data will come from Read the Docs Addons API.
_Note this is just a proof of concept to start the conversation._ While working on the idea to generate the version/language selectors and combine them with the data fetched from Read the Docs API, I realized that if we are migrating only _one_ version to Read the Docs and using a proxy to serve it at the official `docs.python.org` domain, there is no need to use a different version/language selector at all --since all the URLs will be the same and all the JavaScript logic will be the same. The proxy will do the magic to redirect to Read the Docs _only_ the versions configured in the proxy [^1]. However, since when building on Read the Docs the variables `VERSIONS` and `LANGUAGES` are not passed, we need to populate them dynamically with JavaScript when the page is served. **ToDo**: - Populate `all_languages` in the same way. Do we have a JSON file from where we can populate the `LANGUAGES` variable? - Move this `switchers.js` file to https://github.com/python/cpython/tree/main/Doc/tools/static ---- I'm opening a PR here to show what I'm thinking and discuss if this is the approach we want to follow. BTW, the code is not tested. I just wrote it as an example to show what I'm thinking is the direction. Related: - python/python-docs-theme#193 - python/docs-community#5 [^1]: Once all the versions/languages are migrated to Read the Docs, we won't require the `release-cycle.json` nor other file to populate the `LANGUAGES` variable because this data will come from Read the Docs Addons API.
|
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 python/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.
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. |
This is a good point to me as well 👍🏼 . What about adding these JSON files (available versions and languages) in the
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 |
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 |
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