search

jupyterhub / jupyterhub-sphinx-theme

A lightweight wrapper theme for Sphinx based on the PyData Sphinx Theme
https://jupyterhub-sphinx-theme.readthedocs.io/en/latest/
BSD 3-Clause "New" or "Revised" License
0 stars 2 forks source link

Support RTD version selector #8

Open manics opened 1 year ago

manics commented 1 year ago

Proposed change

Older versions of the JupyterHub docs e.g. 3.0.0 had a version selector, allowing you to switch to other versions of the docs.

This seems to have been lost in JupyterHub 3.1.0, probably with the switch to the pydata theme?

Alternative options

Do nothing

Who would use this feature?

Users wanting to view docs for versions of JupyterHub other than the latest

(Optional): Suggest a solution

Instructions in pydata for enabling the version switcher: https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/version-dropdown.html

The main requirement seems to be a JSON file with a fixed URL containing the list of versions. Is this file automatically created by readthedocs, and can we automatically set this URL?

welcome[bot] commented 1 year ago

Thank you for opening your first issue in this project! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out Jupyter's Code of Conduct. Also, please try to follow the issue template as it helps other other community members to contribute more effectively. welcome You can meet the other Jovyans by joining our Discourse forum. There is also an intro thread there where you can stop by and say Hi! :wave:
Welcome to the Jupyter community! :tada:

choldgraf commented 1 year ago

The pydata theme should support RTD dropdowns out of the box...that is weird! Do you see any errors in the JavaScript console?

manics commented 1 year ago

There are no javascript errors.

I've found the original pydata-sphinx-theme PR: https://github.com/pydata/pydata-sphinx-theme/pull/436 It doesn't look like the version selector is automatic- the PR added support for the version dropdown (disabled by default) and also added the repo-specific config to enable the dropdown.

The list of versions is manually managed, it's not automatically detected: https://github.com/pydata/pydata-sphinx-theme/blob/main/docs/_static/switcher.json

The pydata-sphinx-theme release process includes this as a step:

- [ ] Update our version switcher .json file with the new version

choldgraf commented 1 year ago

The JSON switcher is a way to manually have a version switcher if you don't want to use the RTD one (and if you manually want to maintain versions in a single JSON). So maybe there's a feature flag for the RTD one too?