Version dropdown menu in local development mode

[HealthyPear]

I have followed the instructions here for my project and before testing it with a full PR I wanted to check if it worked locally.

Looking at what is done in your code https://github.com/pydata/pydata-sphinx-theme/blob/a8efab4a02e76dfbdd72886b10ff0013d6045451/docs/conf.py#L96

I have a couple of questions:

• here you say

The JSON file needs to be at a stable, persistent, fully-resolved URL

but this is a local path

• shouldn't the relative path be "./xxxx"? without the dot isn't it an absolute path from the root directory of the file system?

Anyway, in both cases, I can't seem to make it work: when I click on the dropdown menu it doesn't open I see only the following

Potential solution

We could add a "developer mode" style solution to make this easier, details here: https://github.com/pydata/pydata-sphinx-theme/issues/647#issuecomment-1127301550

[HealthyPear]

Just to be clearer: my situation now is as follows (for reference, my repo is this one),

under docs/_static/switcher.json I have

[
    {
        "name": "dev",
        "version": "latest",
        "url": "https://protopipe.readthedocs.io/en/latest/"
    },
    {
        "name": "0.5.0 (stable)",
        "version": "stable",
        "url": "https://protopipe.readthedocs.io/en/stable/"
    }
]

where all the URLs work,

and in my conf.py,

from protopipe import __version__

[...]

# VERSIONING
# Define the json_url for our version switcher.
json_url = "https://github.com/cta-observatory/protopipe/tree/master/docs/_static/switcher.json"

# Define the version we use for matching in the version switcher.
version_match = os.environ.get("READTHEDOCS_VERSION")
# If READTHEDOCS_VERSION doesn't exist, we're not on RTD
# If it is an integer, we're in a PR build and the version isn't correct.
if not version_match or version_match.isdigit():
    # For local development, infer the version to match from the package.
    if "dev" in version:
        version_match = "latest"
        # We want to keep the relative reference if we are in dev mode
        # but we want the whole url if we are effectively in a released version
        json_url = "/_static/switcher.json"
    else:
        version_match = "v" + version

html_theme_options = {

    [...]

    "switcher": {
        "json_url": json_url,
        "version_match": version_match,
    },

}

I am using pydata-sphinx-theme 0.8.1

Aside from the fact that I had a typo in my v0.5.0, from the latest version I should at least be able to open the dropdown menu right?

[HealthyPear]

and interestingly, even though my switcher.json clearly defines the latest version as "dev" I still see the name "latest" :/

[damianavila]

The version dropdown button not opening is, most likely, a symptom of a CORS issue, see this comment: https://github.com/pydata/pydata-sphinx-theme/issues/613#issuecomment-1087777104.

Can you try changing:

json_url = "https://protopipe.readthedocs.io/en/latest/_static/switcher.json"

in your conf.py file and let us know if that works on the deployed site.

[HealthyPear]

Unfortunately, it doesn't seem to have worked :(

https://protopipe.readthedocs.io/en/latest/ still shows no dropdown support

I re-checked the URLs in play and they all seem to point to the correct information

I don't expect to be able to switch from the stable to the latest version because in the stable version there was likely already the bug, but I would expect at least to be able to see the 2-item dropdown from the latest version.

[HealthyPear]

I took a look to #613 , but it doesn't seem to be clear what the author did to fix his problem (which could be the same I have)

[HealthyPear]

OK nevermind now it works, I don't know why it wasn't working after the new build, probably it needed some time...

[HealthyPear]

OK so now the official published documentation works, though the other part of the issue is still open: if I work locally and I compile the Sphinx documentation it should still work, right?

[tupui]

@damianavila seems like it might deserves a note in the doc. People from NumPy and other are also hitting this.

I had gotten this to work with some instructions there: https://github.com/scipy/scipy/pull/15380#issuecomment-1016859789

[damianavila]

Probably... I am a little bit reluctant to add pieces in the docs suggesting (explicitly) the usage of an insecure browser session. @choldgraf, any thoughts?

[choldgraf]

One idea: what if the theme supported a path to a local JSON file instead of a purely resolved one, as some kind of special "developer mode" that would raise a warning telling people they should switch to a fully resolved path before publishing their docs?

[tupui]

Thais should not just be a warning just in the console though because lot of users will not open up the dev tools. Or you meant a Sphinx warning?

Another alternative is to have a specific dev url field or a dev mode which when entered a local path would work. The issue would still be there but you have to use explicitly in your code a not production flag.

[choldgraf]

Yep I meant a sphinx warning. Basically this would be a workflow that should only be used for local prototyping.

[tupui]

Would be good 👍

[choldgraf]

Implementation idea

Here's an idea for how this could be implemented, in case anybody would like to try making a PR for this:

1. Define a switcher.json_url_local variable that is meant to point to a local JSON file that the switcher would use
2. Update the Sphinx json_url with it. In the Sphinx update_config callback function, add a few lines that do the following:
   1. If json_url_local is set
   2. Attempt to create a fully-resolved local URL to that file
   3. Update switcher.json_url with this value
   4. Raise a Sphinx warning like DEVELOPER MODE: Local path specified for JSON switcher. Specify a fully-resolved URL before pushing this code into production.
3. Document this pattern. Add some docs suggesting how to use this option for local development of the dropdown (e.g. you could recommend people use requests.get to pull a remote JSON file into the local filesystem for local development only.

[m-ganko]

Hi, I was still not able to make version dropdown work in my local dev mode. I have read related topics and it is not clear why it is not expanding. When I download pydata-sphinx-theme docs dropdown is working, but in my generated docs it is not.

Is there anything specific that needs to be set up besided json_url = "_static/switcher.json"?

[tupui]

Hi, I was still not able to make version dropdown work in my local dev mode. I have read related topics and it is not clear why it is not expanding. When I download pydata-sphinx-theme docs dropdown is working, but in my generated docs it is not.

Is there anything specific that needs to be set up besided json_url = "_static/switcher.json"?

@m-ganko It's difficult to help you without seeing your project and setup. The dropdown should work as seen in many projects. You can try to look at other examples such as SciPy or NumPy for instance. There is not more to do than what the doc says.

[m-ganko]

@m-ganko It's difficult to help you without seeing your project and setup. The dropdown should work as seen in many projects. You can try to look at other examples such as SciPy or NumPy for instance. There is not more to do than what the doc says.

@tupui Yes, I was trying to follow the steps shown in theme docs and other projects, but still could not resolve the issue. I have created reproducible example here, maybe someone will catch where is the problem.

[drammock]

@m-ganko if I clone your repo and follow the readme instructions, and then do python -m http.server -d docs/build/html/ then I get a working dropdown.

It's a known limitation that you can't just open the built HTML file and have the version switcher work.

[m-ganko]

@drammock Ok, thank you, I didn't know about this limitation ;). Using http.server works like you said.

But still I was able to make it work (html opened in browser) by replacing "json_url" with link to github repo file.

[drammock]

I was able to make it work (html opened in browser) by replacing "json_url" with link to github repo file.

ah, interesting. If you figure out how to make it work with the local file path, PR welcome to fix it! Would be nice not to need to launch a local web server.