Generate version selector dynamically via JavaScript#179
Conversation
_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.
We will be using the work we've done at python/cpython#116966 and python/cpython#119541 only, without needing anything else to generate these selectors. |
Sorry, something went wrong.
|
Also also, if we want to generate these selectors at build time, the PR that @AA-Turner wrote python/python-docs-theme#193 should work out of the box on Read the Docs without issues. In that case, we should disable the custom |
Sorry, something went wrong.
|
I'm going to close this PR and continue writing my thinking at python/python-docs-theme#193. I'm sorry for the confusions I could have caused here 😅 |
Sorry, something went wrong.
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.orgdomain, 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
VERSIONSandLANGUAGESare not passed, we need to populate them dynamically with JavaScript when the page is served.ToDo
all_languagesin the same way. Do we have a JSON file from where we can populate theLANGUAGESvariable?switchers.jsfile to https://github.com/python/cpython/tree/main/Doc/tools/staticI'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.
cc @hugovk
Related:
Footnotes
Once all the versions/languages are migrated to Read the Docs, we won't require the
release-cycle.jsonnor other file to populate theLANGUAGESvariable because this data will come from Read the Docs Addons API. ↩