Drop the switcher template URL interpolation, and ask users to provide explicit URLs

[choldgraf]

Context

Currently, we ask users to provide two things for the version switcher: a name and a version.

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

The documentation is then configured with a URL template like https://mysite.org/en/version-{version}/.

We then interpolate the URL of each version according to the template.

However, there are a few limitations of this approach:

• It assumes that the URL structure of each version is the same
• The structure of URLs is strongly tied to each Sphinx build.
  • This means that if there are bugs that generate wrong URL links, it's non-trivial to fix them
  • It also means that if the structure of those versions changes, it's non-trivial to fix them.

Proposal: users should give explicit links in the JSON

Instead of interpolating a link structure based on a template, we could just ask users to provide a url: key for each entry in the JSON configuration. For example, the above structure would become:

[
    {
        "name": "v2.1 (stable)",
        "version": "2.1",
        "url": "https://foo.org/en/stable/"
    },
    {
        "version": "2.0",
        "url": "https://foo.org/en/2.0/"
    },
    {
        "version": "1.0",
        "url": "https://foo.org/en/1.0/"
    },
]

Then, when the Dropdown list is built, there isn't any interpolation, it simply generates a dropdown list of links with names.

I think this has a few benefits:

• It reduces the complexity and assumptions we need to make in generating these lists. I suspect there will be fewer "unexpected surprises" with this implementation, as we recently experienced with the v bug.
• It makes the main JSON configuration more of a "source of truth" and explicit where the versions will point
• It shields us from any bugs or UX problems associated with the need to make changes that depend on a specific Sphinx build.

It does mean slightly more hand-editing of that JSON configuration, but I think that this won't be too bad for most projects. I assume most will only keep maybe 6-12 versions in there, and even larger numbers of versions won't be hard to hand-edit with modern-day text editors.

An added bonus is that it would then be pretty trivial to generate a language dropdown. You'd simply have a second JSON configuration file, with URLs that corresponded to language versions instead of code versions.

ref: this also relates to a bug that was pointed out in #574 (comment)

[damianavila]

This is an interesting idea. I like the simplification/versatility on our side even when the creator pays a little bit more price in terms of manual intervention on the JSON file.

@drammock, since you implemented the core of the version switcher, do you have any thoughts on this proposal?

[choldgraf]

I have a PR just to demonstrate what this would look like here: #604

Would also love feedback from @tupui . I think the question to answer is whether the benefit we get from decreased flexibility outweighs the cost of asking users to manually provide URLs for each version. In my opinion, it's worth it (and IMO makes this feature more understandable and explicit anyway)

[tupui]

@choldgraf I would not mind removing the interpolation since it's not helping much. From a user perspective you have to fill out some information and adding this is not really much work (would actually be simpler to explain in the doc I think. This point was a bit troubling). What is important is to retain the ability to specify any form of URL path.