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 versions switcher dropdown via Sphinx's conf.py
• Fixes links to movement (which were broken due to movement also going multi-version)
• Pins movement dependency to >=v0.10.0 (the version where save_bboxes.to_via_tracks_file was added).

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://ethology.neuroinformatics.dev to https://ethology.neuroinformatics.dev/latest/index.html

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://ethology.neuroinformatics.dev will still resolve to the homepage because of the aforementioned aliasing and redirection.

Any links to specific pages, e.g. https://ethology.neuroinformatics.dev/installation.html, will break, as the new links will become https://ethology.neuroinformatics.dev/latest/installation.html. Luckily I found no such links on this repository.

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.45%. Comparing base (e0d56f9) to head (e119d2d).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #111   +/-   ##
=======================================
  Coverage   99.45%   99.45%           
=======================================
  Files           8        8           
  Lines         553      553           
=======================================
  Hits          550      550           
  Misses          3        3           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[niksirbi]

@sfmig tests are failing on Python 3.10 because movement doesn't support that.

In more detail: I found that in my ethology environment a very old version of movement (v0.0.22) was being installed, which was incompatible with the usage of save_bboxes in the example. That's why I pinned movement>=0.10.0 (the version in which save_bboxes was introduced). But that version required Python >= 3.11.

How would you suggest proceeding? I would favour going to Pyhton >= 3.11 for ethology as well, but I'm not sure if that interferes with anything else...

[sfmig]

Hi @niksirbi, thanks for this!

I usually work with 3.12 and hadn't realised this. Good to know the multi-version docs also serve as a backwards compatibility check for the examples 😅

I would favour going to Pyhton >= 3.11 for ethology

Yes that would be the best! Since ethology is a bit wild 🐯 atm, I don't mind if you want to do this in the same PR (for the sake of "development velocity" 😁) . Also happy if you want to do it in a separate PR tho, or if you want me to do it! Just the latter option may be a bit slow.

Let me know, thanks again for this!

[niksirbi]

Hey @sfmig. I will open a separate PR for Python >3.11. We can merge that first, and then rebase this one to main. I'm happy to do this the 'proper' way.

[niksirbi]

@sfmig this is now ready to review, following a rebase to main after #120 was merged.