Issue #1368 Add Multidoc utiity for creating versioned documentation - #1369
Open
Manangka wants to merge 2 commits into
Open
Issue #1368 Add Multidoc utiity for creating versioned documentation#1369Manangka wants to merge 2 commits into
Manangka wants to merge 2 commits into
Conversation
Copy link
Copy Markdown
Collaborator
Sorry, something went wrong.
Manangka
force-pushed
the
issue_#1368_create_multi_version_documentation
branch
from
fdf4cc8 to
e086ce2
Compare
January 3, 2025 15:02
Copy link
Copy Markdown
|
Sorry, something went wrong.
Copy link
Copy Markdown
Contributor
There was a problem hiding this comment.
Thanks for the efforts, looks good. My main thoughts:
- I'm a bit surprised this required quite some custom code: that there is not a plug and play answer for our usecase. Did you take inspiration from any repositories? Might be good to add here, so we can check how they updated their code whenever this breaks after an update.
- I thought we set up pixi tasks so that all tasks related to our builds are called from pixi. But now we have a python script to run around pixi again? I'm not sure what is preferable here, on one hand having everything in pixi tasks is nicer to use, as developers always know where to look for any build related tasks. On the other hand: A python script calling a pixi task calling a sphinx is less complicated than a pixi task calling a python script which calls a pixi task which calls sphinx...
- This adds some extra complexity to our builds, given the extra custom code. This is because we don't want to rebuild docs for every version, if I'm not mistaken. I see no description online why we are doing this. Some requirements would help here. Could you add that to the issue description?
- The developer docs need to be extended how to run this. Probably you skipped on that in awaiting of my review.
Sorry, something went wrong.
Comment thread
docs/multidoc.py
Comment on lines
+190
to
+195
| subprocess.run( | ||
| ["pixi", "run", "--frozen", "install"], | ||
| cwd=self.work_dir, | ||
| env=env, | ||
| check=True, | ||
| ) |
Copy link
Copy Markdown
Contributor
There was a problem hiding this comment.
Can't this be a dependency of the "sphinx-build" task? If not, please add a comment why
Sorry, something went wrong.
Comment thread
docs/conf.py
Comment on lines
+140
to
+141
| if "JSON_URL" not in env | ||
| else env["JSON_URL"] |
Copy link
Copy Markdown
Contributor
There was a problem hiding this comment.
Please add a comment when JSON_URL is added to the environment when running multidoc.py
Sorry, something went wrong.
Manangka
force-pushed
the
master
branch
2 times, most recently
from
ef47289 to
b33942f
Compare
September 9, 2025 12:54
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Reviewers
At least 1 approving review is required to merge this pull request.
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #1368
Description
This is the first step to having multi-version documentation. The steps needed are:
This commit introduces multidoc.py. This is a small helper script that helps build the multiversion documentation.
It has 3 commands:
When a version is added or updated the version is checkout using the git worktree command.
This creates a separate folder which contains the branch/tag of which we want to build the documentation.
Building the documentation in the worktree is done in the same way as we do it currently
To have multi-version support 2 changes need to be made. In the conf.py file we need to add switcher to the html_options. Furthermore we need to create a switcher.json file which contains all the available version in the documentation.
Since older version don't have the updated html_options a patch file is included. When calling add-version or update-version this patch is appllied. This way we can also build documentation for older version.
The add-version and update-version both build the documentation. The add-version also updates the switcher.json file to contain the new version.
The remove-version command removes the specified version from the documentation and updated the switcher.json accordingly
There are some optional flags that can be used.
A useful one in the --local-build flag. This flag rewrites the documentation url to a local filesystem url. This way you can use the switcher also locally.
When running it locally I did a CORS error from chrome. This can be circumenvented by running"
chrome.exe --user-data-dir="C:/Chrome dev session" --disable-web-security
Checklist