Add version dropdown (for other versions of the docs)

We would like to have a version dropdown to switch to a different version of the docs.

Some examples:

Python docs (https://docs.python.org/3/) (also sphinx based, could look how they do it):

Docker docs (https://docs.docker.com/install/overview/):

Readthedocs theme also supports this (so this could also be worth a look how they do it):

@bryevdv

@bryevdv implemented this for bokeh in bokeh/bokeh#9330 (see https://docs.bokeh.org/en/dev/index.html), so we can port that back to the main theme.

Just some notes about the Bokeh version:

it releases on a version.json file that presumably would get updated automatically or manually during a release. It lists all the versions to go in the menu explicitly
this JSON file also lists all previous releases, and this is used to display alert banners for "old release" or "pre-release" at the top

Also, the code for this is currently in a scripts.html template that gets included in every page. I kind of think it might be better to move the version handling to a completely separate JS file that gets loaded in the scripts template. That way if there is ever a time when maintainers want to update the version handling somehow for all versions of the docs, there is just one JS file per docs version to swap out.

+1 for this. FWIW, spyder just released its docs with a modified version of this theme and it has a version template, javascript,css. I don't see how it determines the document versions to list, I think it is connected to the multidocs sphinx extension. That builds the docs for each version, which is not really portable.

note that we're discussing this issue in #234 as well...not sure if that's a dupe or not

Not sure if it is relevant but just FYI for Bokeh we update/publish a versions.json file as part of our release, that lists the versions that should appear in a menu, as well as specifies the current latest version (so banners get raised when viewing older or dev/rc versions)

At a bare minimum, it would be nice to have an easier place to hook in to add/set-up the version chooser. Right now I need to copy/override the entire navbar to inject the <li> and other elements. Happy to submit a PR if there's some agreement on what including even that would look like.

@dopplershift

@dopplershift There's also #244 that discusses the sidebar injection portion of this; we did something like this in our downstream fork, but in a more limited fashion.

I don't see how it determines the document versions to list, I think it is connected to the multidocs sphinx extension.

Its based on the tags and branches in the repo (and can use the version and release in your conf.py for the URLs and/or UI names, among other things), with a customizable whitelist for each, so you can customize which get shown. In addition, we have automated build scripting we developed that generates redirects, a tag for the current branch, and automatic stable/latest-type names; this could either be reused, packaged or turned into a Sphinx extension, perhaps.

That builds the docs for each version, which is not really portable.

I'm not sure I follow, but would love to hear more about this. Thanks!

As far as I can tell, and correct me if I am wrong, the multidocs sphinx extension builds the docs for every version at every invocation. The workflow for NumPy is to build the release version of the docs off the release tag, and copy that into a github repo numpy/doc (that already contains prebuilt documentation for previous versions).

What about adding a new theme option version_switcher that would accept a list of url's and display names? This would make it pretty easy for downstream packages to simply implement in their conf.py theme options by just passing a list of url's and version display string.

In conf.py:

base_url = 'https://example.com/example/doc/'
version_choices = [
                ('latest', '2.1'),
                ('2.0.2', '2.0'),
                ('1.3.3', '1.3')]
version_choices = [base_url + v[0], v[1] for v in version_choices]

html_theme_options = {'theme_version_switcher': version_choices}

Then this theme could add another nav-item to the nav menu to create the dropdown.

        {% if theme_version_switcher | length > 2 %}
          <li class="nav-item version_switcher dropdown">
            <button id="dLabel" class="btn btn-secondary btn-sm dropdown-toggle" type="button" data-toggle="dropdown"
              aria-haspopup="true" aria-expanded="false">
              {{ theme_version_switch[0][1] }}
            </button>
            <div class="dropdown-menu" style="min-width: 6rem;">
              {% for version in theme_version_switcher %}
              <a class="dropdown-item" href="{{ version[0] }}">{{ version[1] }}</a>
              {% endfor %}
            </div>
          </li>
        {% endif %}

This renders as:

Some things to consider from the examples above too:

everyone is putting the version switcher in different places. Should it be in the nav header, a sidebar, left/right, etc... Should the theme be somewhat opinionated here and just choose one?
Should a version switch be directly linked to the new version's index page? If I'm on page example.com/v2.3/feature/method1, Should the url be switched to: example.com/v1.2/feature/method1 instead of example.com/v1.2? (Spyder does the former, Bokeh does the latter)

@greglucas

@greglucas The problem with that approach is that old versions of docs have to be rebuilt in order to show newer versions in their chooser. That's why the common approach is to put a json file at the top level, where JavaScript within the built docs can read the information on all the available versions and dynamically populate the selector.

Good point! A similar method could easily be wrapped up in a <script> tag to inject the js.
'theme_version_switcher': '/path/to/versions.json'.

Thinking on the fly here though, I think you'd still need to rebuild all of the old docs once initially to inject that script? But, at least it would be a one-time event rather than for each new release as you bring up.

Is there a sphinx package that does this? And if not, I think it could be pretty easy to add a little lightweight one that would:

Let you use html_sidebars to identify a placeholder for the version switcher
Use some javascript to read in JSON as described above and then replace the placeholder with a little dropdown

This theme could then depend on that library to re-use the dropdown if it wanted something in the top-bar

@greglucas

Now that #248 is merged we have access to html_sidebars. This means that it should be pretty straightforward for people to add the dropdown that @greglucas suggests above, probably with the modification that @dopplershift suggests to have a single source of truth for the versions.

As a start, perhaps @greglucas could make a PR that adds a template for a dropdown selector here:

https://github.com/pandas-dev/pydata-sphinx-theme/tree/master/pydata_sphinx_theme/_templates

and then add a configuration option to add it to the list of html_sidebars that is activated by default in this theme? (as well as documentation for how others could add it manually).

Then a next step could be to find a way to add it to the navbar as well, but it seems this would be a good first-step.

Is this still wanted? I can see two PR but they look stalled. I started to add a rough badge on SciPy and I am not sure if I should just wait for it to happen here or not. xref scipy/scipy#14132

I'm working on #360 to add a version switcher and a locale switcher. Here are some things I'm considering:

I think it's better to rename version.json to config.json as both version switcher and locale switcher need to be configured.
Some locale switcher examples:
Vue

Python

ok, thanks for clarifying. I'll assume then that your new PR will be coming soon and I'll save any further feedback for that PR.

Folks, I am looking at this right now... trying to collect and digest all the information (and different implementations) so I am able to provide good and useful feedback in the current open PRs.

You should expect some comments on those PRs soon.
I might also add some other general thoughts here as well as I am understanding things more deeply.

Thanks for your patience and for the contributions!!

@drammock

All,

I have closed the first implementation (#276 because I believe the other two PRs (#433 and #436) are more mature and able to be merged soon.
Particularly, after looking at all the implementations, I have requested some changes in #436 so we can merge that one ASAP and iterate on top of it.

If you @drammock or @ThuWangzw disagree on the proposed path forward, let us know!

@ThuWangzw

@ThuWangzw in case it's helpful, here is how we implemented the version switcher in this theme, in MNE-Python:
https://github.com/mne-tools/mne-python/blob/a22a3ca42687fb63975070cc46ac7754af409732/doc/conf.py#L537
https://github.com/mne-tools/mne-python/blob/ed64dc7bd0750bab2e99a1cfcbce2928eb37e202/doc/_templates/version-switcher.html#L1-L11
https://github.com/mne-tools/mne-python/blob/35e867ad6506d50a4fa1bef71cc2610bf1aad6f3/doc/conf.py#L592-L607

Woo your doc is really nice @drammock 👍 If you have any feedback for SciPy I would be interested 😅

Where can I get the working copy of both versions and languages drop-down, please? Are the above the 3-4 files that are responsible for this functionality ?

@Sachin-Suresh

@Sachin-Suresh please have a look at the documentation https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/version-dropdown.html

Where can I get the working copy of both versions and languages drop-down, please?

the expansion to cover both languages and versions was never implemented (yet).

@tupui

Thanks @tupui. And sorry to continue this discussion on a closed PR. I have been struggling to implement versions and language in Sphinx Readthedocs theme with limited documentation. It would be great if I get some resources on this as I am new to Sphinx. I would still try the Version switcher documentation Tupui had shared.

feat: publish versioned documentation at release time

Navigation Menu

Repository navigation

Add version dropdown (for other versions of the docs) #23

15 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Add version dropdown (for other versions of the docs) #23

Description

Activity

jorisvandenbossche commented on Oct 28, 2019

bryevdv commented on Oct 28, 2019

mattip commented on Sep 1, 2020

choldgraf commented on Sep 1, 2020

bryevdv commented on Sep 1, 2020

dopplershift commented on Sep 1, 2020

CAM-Gerlach commented on Sep 8, 2020

mattip commented on Sep 9, 2020

greglucas commented on Sep 9, 2020

dopplershift commented on Sep 9, 2020

greglucas commented on Sep 9, 2020

choldgraf commented on Sep 26, 2020

choldgraf commented on Oct 11, 2020

tupui commented on Jul 18, 2021

ThuWangzw commented on Jul 19, 2021

15 remaining items

drammock commented on Jul 20, 2021

damianavila commented on Nov 18, 2021

damianavila commented on Nov 23, 2021

Sachin-Suresh commented on Aug 25, 2022

tupui commented on Aug 25, 2022

drammock commented on Aug 25, 2022

Sachin-Suresh commented on Aug 26, 2022

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions