Replies: 5 comments 17 replies
-
|
I'm not sure about the readthedocs suggestions as I didn't understand how it will work. |
Beta Was this translation helpful? Give feedback.
-
|
I'll add more details on the readthedocs option. ReadTheDocs (RTD) is a service designed to host websites with multiple versions and/or languages and simplify the process of publishing and versioning among other potential challenges. In the cookbooks case, as it already uses jupyterbook which is based on sphinx, using readthedocs to build and host the website would be quite straightforward. At most it would mean converting the Once the RTD project has been created, any branch or tag within the github repository can be published as a different version from the RTD dashboard. On RTD, documentation versions can have 3 statuses: active (published and visible on the version switcher), hidden (published but not visible on the version switcher, e.g. to keep the number of version small but avoid breaking links that point to it) and inactive (not published). Language versions are a bit more complex to set up. They require an extra readthedocs project per language which is then linked from the RTD dashboard to the main project. This can only be done by someone who is an owner of both RTD projects, so the maintainers should be added to the main RTD projects and all the translation ones. The translation RTD projects can be linked to this same GitHub repository or to a different one. Once the different versions and languages are configures, RTD adds a flyout switcher that when clicked on shows all the active versions and languages. For example, from the sphinx docs which have 1 active version and multiple languages available: The contents of the switcher are updated automatically whenever versions or languages are modified through the RTD dashboard. This would hand off part of the complexity of the projects. It would still be necessary to agree on a versioning scheme and to translate and define how to build standalone versions of the translated cookbook. |
Beta Was this translation helpful? Give feedback.
-
|
I have gone over the cpython setup and I'll try to describe at a high level focusing on the elements I think are relevant to us to as well as I can. I am starting a new thread because their whole process is extremely complex, thankfully the extracted version/language logic not so much. The python documentation website (everything inside docs.python.org is build using the infrastructure in https://github.com/python/docsbuild-scripts. These scripts are executed automatically from a cron for the python versions that are in active. Cadence wise it looks like once a day for translations, a couple times per day for english version based on. The metadata about the languages is in this repository Important Both versions and languages are static in the python docs. The elements of the switchers are added at the time of building, and updating either of the two metadata documents doesn't update the switchers. Some examples: if you look at the 3.13 English version the versions available range from 2.6 to 3.15 whereas 3.0-3-4 have no version nor language switcher and 2.7 has versions 3.5-3.10 and is missing several languages. To build the documentation, the main cpython repository is cloned and the requested branch is checked out, and if building a translated version the corresponding translation repo is also cloned into the locale directory and has the matching branch checked out. Tags are used for code releases but the docs are not built from the tags, not even the English version. Then sphinx is triggered to build the docs, they have their own custom theme and some extra functionality within If we wanted to follow a similar pattern but without multiple repositories, I believe that would mean having a branch per release (where content is frozen, maybe it could even be enforced with pre-commit in a github action to make sure only the locale folder can be updated once a branch is "released") and the multiple translations inside that branch as a locale folder (which is what the repo looks like in the cpython setup after cloning the translation repos). We would then have a GitHub action to build all the languages and in that process inject the existing versions and languages into the html. As mentioned, this has the significant drawback that old versions are not aware of newer ones which is one of the most common navigations we'd want visitors to do. One of the nice features of having specific repositories for translations is that most things within the translation repos are in the target language (e.g. python-docs-es is mostly in spanish) which allows people who don't speak English to contribute. They obviously can't translate but the cpython docs are huge so pages are translated, reviewed and also proofread (that is, read by people who have not read the original version to make sure the translation by itself makes sense and is coherent). We might want to start with a simpler workflow though. |
Beta Was this translation helpful? Give feedback.
-
|
I am opening yet another thread to discuss not what other projects do but specific proposal for our case. The cookbook uses the sphinx-book-theme which is based on the pydata-sphinx-one and supports a version switcher with dynamic version metadata so older versions will show newer ones on their switcher. On the other hand, I think it is ok to prevent adding new languages on older versions, and if we add new languages do so only on the most recent version. Consequently, the language switcher can be static like cpython docs do (kind of global version switcher but version specific language switcher). I would still use branches for releases so ongoing translations can be finished but we could even use tags. If we really want to enforce released branches not getting their content updated we could use pre-commit or github actions on PRs to check only files within the We would therefore have a Implementation wise, that would represent switching from config.yml+jupyterbook to conf.py+sphinx-build (only these two files would need to change, no changes to content or even the toc.yml), a couple tens of html-jinja lines for the html template, the jsons with the metadata and ~5 lines in conf.py to configure the theme provided switcher. I propose this to be part of the version project. We would then need github actions to 1) build and deploy the website into the corresponding subfolders (update existing one, if possible by using the languages.json to repeat the build step for each language which seems possible and 2) generate po/pot files and push/pull them from whatever service we use for collaborative translations. I propose 1 to be part of the version project, 2 (along with defining when to do that and what service to use, if at all) to be part of the translations project. In addition, it will also be necessary to properly style the switchers to look nice and similar to each other and to be responsive/available somewhere in all screen sizes. As it depends on the html elements being there, it should be assigned to the project that adds the switchers. It would also be extremely helpful to get something similar to 1 (something that builds all languages for the current version/branch) to do the same for each PR and add a link to a preview. Not sure which project should take care of that In my opinion, the rest of the tasks are better separated:
|
Beta Was this translation helpful? Give feedback.
-
|
I was exploring how Spyder handles versioning in their documentation, and I wanted to share my findings about their approach. Spyder uses a branch-based versioning system rather than tags. Each major version has its own dedicated Git branch:
This approach allows maintaining separate documentation versions simultaneously, making version-specific updates easier while keeping older versions accessible. Tag-based versioning creates immutable snapshots at specific points in time, whereas branch-based versioning supports ongoing maintenance of older documentation. With tags, each update would require creating a new version tag, which makes it difficult to fix typos or add clarifications to older versions. The core of the version switcher is The version switcher appears in the navigation bar, letting users easily toggle between documentation versions. It's implemented using:
When a user switches versions, the system tries to find the same page in the target version, falling back to the version homepage if that specific page doesn't exist in the other version. Spyder organizes their documentation URLs clearly:
The versioning is handled by Netlify's branch deployment capabilities netlify.toml , ci :
Netlify handles the mapping between branches and URL paths, which keeps each version independent while maintaining them under one domain. (I think we can also use GitHub Pages to achieve similar versioning in the Cookbook repo using custom GitHub Actions.) Looking at the line 46-47: LATEST_VERSION = 5
BASE_URL = "https://docs.spyder-ide.org"These constants define the current version number (5) and base URL. When they want to release a new version, they just need to update this LATEST_VERSION constant (after first creating a new branch from master to preserve the previous version documentation) There's a function called This function basically:
For local development, after setting up a virtual environment, these commands can be run to view documentation in the local browser: nox -s build and nox -s serve. The nox -s build-deployment . This only builds the current branch's documentation. When I clicked the version switcher during local development, it redirected me to the live site (rather than any local version) because the URLs in versions.json point to the production site (e.g., https://docs.spyder-ide.org/4/). Since the other version directories don't exist locally, and the versions.json file uses absolute URLs rather than relative paths. The language switcher works similarly to the version switcher, using a language-specific JSON configuration. If anything I’ve shared is inaccurate or could be improved, I’m absolutely open to feedback and happy to make corrections. i am currently exploring GitHub Actions and the scikit-learn repository to understand how they implement versioning. @OriolAbril Could you please suggest relevant documentation links that i should explore for my project? |
Beta Was this translation helpful? Give feedback.







Uh oh!
There was an error while loading. Please reload this page.
-
As we have two GSOC projects (#315, #316) that will add switcher to the book website, it makes sense to discuss how we are going to add these two dimensions to the projects can maintain some independence.
Two suggestions from @OriolAbril:
Personally I would prefer to see us not rely on readthedocs. While I think it is a great service, I don't know that we want to require the book to be served there rather than on Github Pages as it is done now.
@speco29 and @AR21SM, let us know if you need any guidance but we should probably solve this before working too much on either independent project
Beta Was this translation helpful? Give feedback.
All reactions