Set up multi-version docs

[niksirbi]

Description

What is this PR

• Bug fix
• Addition of a new feature
• Other

Why is this PR needed?

To be able to view multiple versions of the docs, including for past versions.

What does this PR do?

• Uses the deploy_sphinx_docs_multiversion action instead of deploy_sphinx-docs
• Adds a version switcher dropdown via Sphinx's conf.py
• Updates some links in the README

This new setup:

• deploys each version of the docs to a separate folder named after the release tag (e.g. v0.5.1),
• deploys all merges to main (without a tag) to a special dev folder
• adds a version-switcher dropdown listing all deployed releases plus dev.
• aliases latest to the most recent release
• redirects https://datashuttle.neuroinformatics.dev to https://datashuttle.neuroinformatics.dev/latest/index.html

As a side effect of how the doc_version for the dropdown is derived, the release name (displayed on the top left next to the logo) will now be parsed as datashuttle v{MAJOR}.{MINOR}.{PATCH}.dev{N} instead of just datashuttle v{MAJOR}.{MINOR}.{PATCH}. However this will only affect "dev" versions. The "latest" version (shown by default) will be displayed as datashuttle v{MAJOR}.{MINOR}.{PATCH}, same as any other tagged release version.

References

The 2 movement PRs that this one is based on:

• Changes for multi-version docs movement#668
• Fix issues with multi-version docs movement#700

Relevant issues/PRs of the actions repo:

• Action for deploying multiple versions of Sphinx docs actions#91
• Add action for multi version deploy of docs actions#93
• Multi-version docs dropdown should only list MAJOR.MINOR versions actions#118

How has this PR been tested?

This has been successfully tested on the movement and NeuroBlueprint websites.

To observe the full effects of this change, we need to make a new release after merging this PR, and I recommend doing this soon after merging.

After we are happy with the changes, we can also clean up the old contents of gh-pages, i.e. delete all root contents other than:

• index.html
• .nojekyll
• CNAME
• folders created by the new action, i.e. dev and v{MAJOR}.{MINOR}.{PATCH}.

Is this a breaking change?

No.

https://datashuttle.neuroinformatics.dev will still resolve to the homepage because of the aforementioned aliasing and redirection.

Any links to specific pages, e.g. https://datashuttle.neuroinformatics.dev/pages/get_started, will break, as the new links will become https://ethology.neuroinformatics.dev/latest/pages/get_started. Luckily I found only 2 such links in the entire project (both in the README).

Does this PR require an update to the documentation?

No.

Checklist:

• The code has been tested locally
• Tests have been added to cover all new functionality
• The documentation has been updated to reflect any changes
• The code has been formatted with pre-commit