Is your feature request related to a problem? Please describe.
Thanks to @animeshsasan’s work in #93, we now have a deploy_sphinx_docs_multiversion workflow that:
- deploys each version of the docs to a separate folder named after the release tag (e.g.
v0.11.1),
- deploys all merges to
main to a special dev folder, and
- adds a version-switcher dropdown listing all deployed releases plus
dev.
You can see this in action on the websites of movement and NeuroBlueprint.
The issue is that with frequent releases, the dropdown will soon become too long and unwieldy, and the contents of the gh-pages branch will grow substantially in size.
Describe the solution you’d like
This improvement was originally proposed by @lochhh.
Instead of deploying each patch version to its own folder, we could keep one folder per minor release, with patch releases simply overwriting the existing folder. The dropdown would then only list MAJOR.MINOR versions—similar to how NumPy’s documentation is organised.
Example:
- Releasing
v0.11.0 → creates a new folder named v0.11 and adds a dropdown entry.
- Releasing
v0.11.1 → overwrites the contents of v0.11; the dropdown remains unchanged.
- Releasing
v0.12.0 → creates a new folder named v0.12 and adds a new dropdown entry.
This approach would keep the version dropdown manageable and limit the number of folders on gh-pages, while still preserving the key purpose of multi-version docs. The trade-off is minimal, as patch releases shouldn’t introduce significant API changes.
Is your feature request related to a problem? Please describe.
Thanks to @animeshsasan’s work in #93, we now have a
deploy_sphinx_docs_multiversionworkflow that:v0.11.1),mainto a specialdevfolder, anddev.You can see this in action on the websites of movement and NeuroBlueprint.
The issue is that with frequent releases, the dropdown will soon become too long and unwieldy, and the contents of the
gh-pagesbranch will grow substantially in size.Describe the solution you’d like
This improvement was originally proposed by @lochhh.
Instead of deploying each patch version to its own folder, we could keep one folder per minor release, with patch releases simply overwriting the existing folder. The dropdown would then only list
MAJOR.MINORversions—similar to how NumPy’s documentation is organised.Example:
v0.11.0→ creates a new folder namedv0.11and adds a dropdown entry.v0.11.1→ overwrites the contents ofv0.11; the dropdown remains unchanged.v0.12.0→ creates a new folder namedv0.12and adds a new dropdown entry.This approach would keep the version dropdown manageable and limit the number of folders on
gh-pages, while still preserving the key purpose of multi-version docs. The trade-off is minimal, as patch releases shouldn’t introduce significant API changes.