Version dropdown: should the "version_match" match the version or the name of the version?

[jorisvandenbossche]

See https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/configuring.html#configure-switcher-version-match for the explanation of the feature.

For the configuration of the version dropdown, you provide a json like

[
    {
        "name": "v2.1 (stable)",
        "version": "2.1"
    },
...
]

and so when specifying the switcher['version_match'] in conf.py, there are two potential things that it could match: the "name" or the "version" from the json file.

Currently, it tries to match the version:

pydata-sphinx-theme/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/_templates/version-switcher.html

Lines 68 to 75 in ef7d5a2

	// replace dropdown button text with the preferred display name of
	// this version, rather than using sphinx's {{ version }} variable.
	// also highlight the dropdown entry for the currently-viewed
	// version's entry
	if (entry.version == "{{ theme_switcher.get('version_match') }}") {
	node.classList.add("active");
	$("#version_switcher_button").text(entry.name);
	}

While starting to use the version dropdown for the pandas docs, I actually implemented this to match the "name" (pandas-dev/pandas#45370). The reason for this is because our "version" needs to follow the url scheme, and for historical reasons this is a bit complicated (so in our versions.json, the "name" entry is simpler)

Now, our case might of course be a bit specific.
But so that did me wonder in general which of the two would in practice be the most useful to try to match?

(cc @drammock)

[drammock]

ha, good catch. I'm actually not sure if this is working or not for MNE-Python because I didn't backport the theme's switcher to our stable docs, but I suspect that if I did, it wouldn't work. In fact for us it would probably still not work if we matched against entry.name. We currently do a little magic in conf.py so that the match succeeds for the dev version:

release = mne.__version__  # The full version, including alpha/beta/rc tags.
version = '.'.join(release.split('.')[:2])  # The short X.Y version.
# (we need something like ↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓ for "stable" too!)
switcher_version_match = 'dev' if release.endswith('dev0') else version
html_theme_options = {
    # (other entries omitted for brevity)
    'switcher': {
        'json_url': 'https://mne.tools/dev/_static/versions.json',
        'url_template': 'https://mne.tools/{version}/',
        'version_match': switcher_version_match,
    }
}

I don't know if that would be enough to fix things in the pandas case? Because I'm not familiar with the URL versioning scheme you folks use. MNE-Python uses this:

version	URL	dropdown "version"	dropdown "name"
1.0	dev	dev	1.0 (devel)
0.24	stable	stable	0.24 (stable)
0.23	0.23	0.23	(empty)
0.22	0.22	0.22	(empty)
0.21	0.21	0.21	(empty)
...	...	...	...

which is... messy.

[drammock]

to say something a bit more coherent about this:

The problem that I think has been revealed here is that the version value of a given entry in versions.json needs to do two things: (1) match against a version_match value from conf.py when the docs are built, and (2) be the correct form to insert into a template URL to make it valid. If you wanted to match against entry.name instead, then you'd need a way to generate the "display name" of the version within conf.py and also hard-code it in versions.json --- not impossible but seems like extra effort? (you need variables release and version in conf.py for sphinx anyway, why not use one of them?)

That said, maybe these two things could be decoupled. If each versions.json entry had a new key (url_string?) that is what gets inserted into the template URL, that might make things a lot easier / more flexible for projects where the URL scheme is messy for historical reasons. This new url_string could be optional (like name, it could default to the same value as version if undefined).

[jorisvandenbossche]

So for pandas, that table looks something like:

version	URL (after pandas.pydata/org/)	dropdown "version"	dropdown "name"
1.5.0.dev	docs/dev	docs/dev	1.5 (dev)
1.4.0	docs	docs	1.4.0 (stable)
1.3.5	pandas-docs/version/1.3	pandas-docs/version/1.3	1.3.5
1.2.5	pandas-docs/version/1.2	pandas-docs/version/1.2	1.2.5
1.1.5	pandas-docs/version/1.1	pandas-docs/version/1.1	1.1.5
...	...	...	...

Currently, I use this long dropdown "version" that includes a larger part of the url, to overcome the messy url scheme (for historical reasons). Now, the idea of being able to override the "url_template" (#573), could maybe also used here to simplify the "version", and make it easier to match that version.

And because of that complexity in the dropdown "version", in our case it's actually simpler to construct the dropdown "name" in our conf.py. But this problem will of course not be something generic.

[jorisvandenbossche]

Something else that I noticed with the "matching" of the version, is that the documentation needs to be built specifically for a specific version.
Especially for the "stable" docs, for the matching to work, those docs need to be specifically be "built as stable docs". Assume your last release is 1.3, and you built the docs for 1.3, then the dropdown version might be "stable". But if you then have a next release, you can simply copy those docs to a /1.3/ folder, as you also need to update the "version_match" in the conf.py and rebuilt those docs.
This might be obvious, but eg in the case of pandas, our "stable" docs are actually a symlink to a specific version, and on release we update the symlink to point to the correct docs. With such an approach, this "version matching" will also never work.

---

It's actually also not working on our own demo docs, but I think this has two reasons:

1. we don't do a good (consistent) job of bumping our "dev" version in __init__.py, which is currently still hardcoded as "0.7.1" instead of being something like "0.7.1+.." or "0.8.0dev0" (at the moment be just bump that version when doing a release, in the past we had the habit to also bump it to a dev version after each release)
2. we also haven't updated our switcher.json to include the latest release or a dev version (we should update our release instructions to update this file in addition to the version itself)

[12rambau]

I think since the beginning of the year the documentation of the version switcher is now well explained. Is it still an issue ?

[12rambau]

This issue is on pause for several months and it's working on the latest pandas documentation version and on our site as well.

The initial question is answered here :
https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/version-dropdown.html#add-a-json-file-to-define-your-switcher-s-versions

We are matching on version as name is an optional parameter.