[WIP] Provide version dropdown in docs

[Bi0T1N]

Description

This provides a dropdown in the docs on the right side to select the desired docs for a specific version.

Related Issue

Resolves #4537

Motivation and Context

A dropdown in the docs will improve the user experience and ease the understanding which version of the docs are currently viewed (see #4537).
It also allows to switch between multiple versions but this needs more changes since the docs for all versions need to be published. Dropdown selection for versions is used very often in documentation (e.g. https://docs.python.org/3.14/) and the design is inspired by ROS 2

How Has This Been Tested?

By running the commands in a devcontainer that are provided in the docs subfolder. Browsing the docs was tested with Firefox under Linux.

Screenshots (if appropriate):

Checklist:

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my changes.
• All new and existing tests passed.

[sonarqubecloud]

Quality Gate failed

Failed conditions
B Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

[Bi0T1N]

The remaining issue is that the docs for different versions need to be created and published. Currently there are only docs for 5.12 and latest. But I couldn't find where this is done. Or is this a manual task? 🤷

[arturcic]

The remaining issue is that the docs for different versions need to be created and published. Currently there are only docs for 5.12 and latest. But I couldn't find where this is done. Or is this a manual task? 🤷

v5.12 I manually ported back into the main branch, but I think we can automate this at publishing minor/major versions, @gep13 could probably help us with some suggestions

[Bi0T1N]

Currently the website uses the gh-pages branch in this repository for GitHub Pages and I think we could use an approach as described here. This approach might also work by adapting the code in the PublishDocs.cs but I assume this might be a bit more complex than using the existing features offered by GitHub workflow.

• The workflow for the default branch would build the HTML files for each commit and place them into e.g. a /dev folder for the latest docs
• Once a release is created, the main branch gets forked and the workflow detects that it is a release/branch by matching github.ref_name against ^[0-9]+\.[0-9]+\.[0-9]+$ and thus publishes to e.g. the /v6.0.0 folder now. This would also allow fixes to docs in the release branch afterwards since it would just update the files inside that folder - if this is desired at all because normally a release is frozen. Otherwise it is run on a tag (which seems to be the case for 99% of the releases of GitVersion) and forget about fixing docs for released versions.
• The drawback is that you cannot link to the v6.0.1 release from the v6.0.0 docs because that would require that you always update the Navbar file in all existing releases for each new release but it will provide links to older and the latest (/dev) release. From there you can reach all other releases. (If this is important I guess it could be solved by using a single Navbar file for all version folders)
• The existing publish workflow would probably only need to build the HTML docs, run actions/upload-pages-artifact and finally actions/deploy-pages.
• The gh-pages branch is no longer needed. Otherwise it should be possible to use an similar approach and push the folders to the branch and trigger a workflow to deploy the pages from there.