The version switcher looks for json_url in an incorrect location when arbitrary static paths are used

[agriyakhetarpal]

Description

A local JSON file located in a source in html_static_path supplied with the version switcher options will be found by the theme upon building the documentation in said path, but json_url will return a 404 status code upon accessing the built documentation, which will break the version switcher.

As discussed with @drammock, this is likely related to #1385 and #1328.

Minimal working example

In conf.py

import xyz


version = xyz.__version__

html_static_path = ["abc/xyz/_static"]

html_theme_options = {
    ...,
    "switcher": {
        "version_match": version,
        "json_url": "abc/xyz/_static/versions.json",
    }

and in versions.json

[
    {
        "name": "latest",
        "version": "latest",
        "url": "https://docs.xyz.org/en/latest/"
    },
    {
        "name": "stable",
        "version": "stable",
        "url": "https://docs.xyz.org/en/stable/"
    },
    {
        "name": "v1.2.3",
        "version": "1.2.3",
        "url": "https://docs.xyz.org/en/v1.2.3/"
    }
]

The theme is able to find the versions.json file without issues since it does not display a warning. The issue arises when the documentation is built and accessed, wherein there is a mismatch; it tries to find the switcher at https://localhost:8000/abc/xyz/_static/versions.json and fails, thereby causing the dropdown to not load, while Sphinx copies over the static file at https://localhost:8000/_static/versions.json.

Apparently, the switcher will work fine for most users since the standard path is set to docs/_static/, which means that the theme will be able to find the json_url at https://localhost:8000/_static/versions.json without issues. The intended functionality is that for arbitrary static paths set in html_static_path, it should still look at the same link instead of appending the path to the static folder in the URL (i.e., at _static/versions.json instead of abc/xyz/_static/versions.json).

Footnotes

xref: pybamm-team/PyBaMM#3108

[maxnoe]

Even when using _static/versions.json, the version switcher will be broken on pages below the toplevel, since a relative url is inserted and then the browser is looking at, e.g. foo/_static/versions.json.

Giving the absolute path /_static/versions.json will result in a working web page, but the check of the file will not work, since it tries to read the absolute path as is, not checking the html_static_path setting.

[drammock]

From the documentation (first sentence of this section):

The JSON file needs to be at a stable, persistent, fully-resolved URL (i.e., not specified as a path relative to the sphinx root of the current doc build).

However later in that same section we say:

The JSON could be saved in a folder that is listed under your site’s html_static_path configuration. See the Sphinx static path documentation for more information.

...which is probably what led you all to think that this would work. I think we should remove (or change wording of) that bullet. There may indeed be something wrong with how we're handling _static (see aforementioned #1328 and #1385) but honestly I don't recommend using a relative path for the JSON URL; even if the JSON were correctly found each time, old versions of your docs won't include dropdown links to the newer versions (because the JSON they link to won't include entries for those newer versions). I'll open a PR to edit that documentation / change the guidance; sorry but realistically I won't have time to chase down a robust solution that allows relative paths in json_url.