Docs: Deploy Multiple Versions

[till-m]

Is your feature request related to a problem? Please describe. Currently, we are hosting one version of the docs, specifically a version that is synced with master. However, users might be using older versions of the package. Even if using the most recently released version, this can differ from master (e.g. see #500).

Describe the solution you'd like Sphinx does, in principle, support a collapsible nav item for multiple versions, see e.g. in this example (bottom left). Ideally, this would store the documentation of each tagged version and master, defaulting to the highest-versioned release.

References or alternative approaches Relevant links:

• Blogpost about this topic
• Stackoverflow answer discussing an implementation
• GH Action: Publish to subdirectory

Examples:

• Conan
• rinohtype

Additional context Does not need to be retroactive -- i.e. once we have it deployed we can simply add versions going forward.

Are you able and willing to implement this feature yourself and open a pull request?

• [ ] Yes, I can provide this feature.

Unfortunately, I don't think I am capable of adding this myself.

[phi-friday]

Have you considered using readthedocs? I've done this before, so I don't remember exactly, but all you need to do is write a .readthedocs.yaml file like this

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.12"
  jobs:
    post_create_environment:
      - pip install uv
      - uv pip compile --extra docs pyproject.toml -o requirements.txt
    post_install:
      - pip install -e .

python:
  install:
    - requirements: requirements.txt

sphinx:
  configuration: src/docs/conf.py

[till-m]

I think it is indeed quite easy with RTD, but considering that we have to pipeline in place to host via GH pages, I'd like to handle it here, if possible...

[till-m]

For the record, I've started to look into this. I think I can get this work with if we're okay with switching the theme to sphinx-immaterial.