Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Deploy Multiple Versions #504

Closed
1 task
till-m opened this issue Jul 19, 2024 · 3 comments · Fixed by #509
Closed
1 task

Docs: Deploy Multiple Versions #504

till-m opened this issue Jul 19, 2024 · 3 comments · Fixed by #509

Comments

@till-m
Copy link
Member

till-m commented Jul 19, 2024

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:

Examples:

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
Copy link
Contributor

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
Copy link
Member Author

till-m commented Jul 20, 2024

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
Copy link
Member Author

till-m commented Jul 26, 2024

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants