Issue #1368 Add Multidoc utiity for creating versioned documentation

[Manangka]

Fixes #1368

Description

This is the first step to having multi-version documentation. The steps needed are:

1. Create multi-version documentation
2. Clear the gh-pages branch. Add manually the master documentation to gh-pages and disable the deploy documentation pipeline
3. Update pipeline to update master documentation each time a PR is merged to master
4. Refactor "deploy documentation" to create and add the deployed version documentation
5. Add older versions to the documentation
6. Add helper pipeline to manually remove versions from the documentation

This commit introduces multidoc.py. This is a small helper script that helps build the multiversion documentation.
It has 3 commands:

• add-version
• update-version
• remove-version

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

• Links to correct issue
• Update changelog, if changes affect users
• PR title starts with Issue #nr, e.g. Issue #737
• Unit tests were added
• If feature added: Added/extended example

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[JoerivanEngelen]

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.

[JoerivanEngelen]

Can't this be a dependency of the "sphinx-build" task? If not, please add a comment why

[JoerivanEngelen]

Please add a comment when JSON_URL is added to the environment when running multidoc.py