ENH/MAINT: Version switcher from the sphinx theme #15380

tupui · 2022-01-07T12:21:16Z

Use the version switcher provided by the theme instead of our custom CSS/HTML solution.

I added all versions I saw on https://docs.scipy.org. I am still unsure about how to handle the dev and PR versions. Let see how it goes.

Once this is done, we can decide if we want to remove https://docs.scipy.org or not. The caveat of this method is that when switching to an old version, the version switcher will disappear. So we have to go back to latest to change again the switcher if we want to go to another version.

tupui · 2022-01-07T13:24:57Z

@jorisvandenbossche is this really released (it's live in the doc although there is no doc for 0.7.2, just 0.7.1) or did I miss a step? On master I can see the template but not on the release branch 0.7.x.

I get this on 0.7.2

WARNING: unsupported theme option 'switcher' given
...
Reason: TemplateNotFound('version-switcher.html')

Also I have a question, for SciPy we have a dynamic url when we make a PR. How should I handle this case? For the dev deployed on our main vs released versions, I think I can use some conditions in the config file as I did now. I could do something a bit more involved with re-writing the json file to also handle PRs. But maybe there is another simpler way to define such things?

Last question I have for now, is there an automatic way to style the version switcher? If you look at our current switcher, it would change colour depending on whether it's a release, dev or something too old (and we picked sensible colours for colour deficient readers).

jorisvandenbossche · 2022-01-07T16:46:24Z

No, it's not yet released. Hopefully there will be a 0.8.0 shortly that includes this, until then you will have to test with the master branch.

Also I have a question, for SciPy we have a dynamic url when we make a PR. How should I handle this case?

Good question, I am not fully sure what the best solution is. Are you using readthedocs or something like circle ci to host the docs from the PR?
We currently have the same problem at https://github.com/pydata/pydata-sphinx-theme itself for PRs, where the version switcher doesn't work. We should probably open an issue there. (potentially by using a relative path for the switcher json, but need to re-check some discussion related to that in pydata/pydata-sphinx-theme#436)

Last question I have for now, is there an automatic way to style the version switcher?

The version switcher block has a specific ids on the different elements that can be used for styling. But that's of course for general styling, identical across all versions (unless you would vary the css depending on the version).
I know that mne-python did something similar before, and also mentioned they lost this version-specific coloring while migrating to the upstream version switcher (mne-tools/mne-python#9916, cc @drammock). So it it is something several projects would want, we should see how we can enable this (or document how to do it).

tupui · 2022-01-07T17:05:05Z

No, it's not yet released. Hopefully there will be a 0.8.0 shortly that includes this, until then you will have to test with the master branch.

Ok thanks 🙏 I will play with master then.

Good question, I am not fully sure what the best solution is. Are you using readthedocs or something like circle ci to host the docs from the PR?

It's CircleCI for us and we have a link in the PR to see the artifact.

We currently have the same problem at https://github.com/pydata/pydata-sphinx-theme itself for PRs, where the version switcher doesn't work. We should probably open an issue there. (potentially by using a relative path for the switcher json, but need to re-check some discussion related to that in pydata/pydata-sphinx-theme#436)

I thought I could manually rewrite the config by intercepting the final URL. A simpler way would be that if you select a version that does not exists it gives the current build. This way we don't need to know the dynamic url. That would solve everything for us I think 🤔 Because the deployed dev can have a fix "dev" version since the url is constant (what I intended to do in this PR) and for the PRs it would fail to resolve and use the current build.

The version switcher block has a specific ids on the different elements that can be used for styling. But that's of course for general styling, identical across all versions (unless you would vary the css depending on the version).

I know that mne-python did something similar before, and also mentioned they lost this version-specific coloring while migrating to the upstream version switcher (mne-tools/mne-python#9916, cc @drammock). So it it is something several projects would want, we should see how we can enable this (or document how to do it).

If there is an id we can hack something as it's currently the case (although the release of our doc does not have the version for some reason, another problem...).

But yes having an optional flag in the json could be handy. We can change the name already, having other options could.

drammock · 2022-01-07T19:56:08Z

So it it is something several projects would want, we should see how we can enable this (or document how to do it).

something that I think @larsoner suggested was that you could add a extra_classes field into the version JSON. For example, we might

add "extra_classes": ["dev"] here:

https://github.com/mne-tools/mne-python/blob/2d5d1686e9b06a1e7bc29794bd2084b0336f0ded/doc/_static/versions.json#L2-L5

the theme would dynamically add ~~that classname~~ classname(s) associated with the version being displayed to the switcher button at load time, and
our CSS could target that classname to override the default button styling.

Step 2 requires some new JS in the theme, the rest is done per-project.

tupui · 2022-01-10T07:18:11Z

So it it is something several projects would want, we should see how we can enable this (or document how to do it).

something that I think @larsoner suggested was that you could add a extra_classes field into the version JSON.

This would be good I think.

tupui · 2022-01-16T15:58:26Z

0.8 just got released, I will have a look again.

jorisvandenbossche · 2022-01-17T10:51:22Z

I opened an issue at pydata/pydata-sphinx-theme#566 for the version-specific styling

tupui · 2022-01-17T10:55:52Z

Thanks @jorisvandenbossche for opening the issue!

Can you have a look at this PR? I am not sure if I did it right. It seems to be working like that but I am not sure I understand why because it does select "dev" but does not redirect to http://scipy.github.io/devdocs/ as I would have thought.

As for CircleCI, once the above is sorted out, I would just have detected that we are in the CI and disabled the version switcher.

jorisvandenbossche · 2022-01-17T11:09:46Z

If you check the browser console, you can see something like "Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at https://github.com/tupui/scipy/blob/version_switcher/doc/source/_static/version_switcher.json. (Reason: CORS header ‘Access-Control-Allow-Origin’ missing). Status code: 200".
We ran into that on the PR that developed the version switcher as well, and I suppose this is the reason it is not working properly.

tupui · 2022-01-17T16:58:14Z

Thanks @jorisvandenbossche. After disabling CORS it was not working first because the JSON was not loading properly due to an extra comma at the end of the JSON. Maybe some warning would be nice here in case it fails to load the file. That would have helped me.

open -n -a /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome  --args --user-data-dir=”/tmp/chrome_dev_test” --disable-web-security

Anyway, it's working now: when it loads, the current build is live (we are not directly redirected to url_template which is convenient). I can select another version and then it would follow the template url. The only issue I see now is that it cannot go back to the dev version because it would not match any URL (https://docs.scipy.org/doc/scipy-dev/reference/), but this can be fixed with a redirection on our side.

tupui · 2022-01-17T18:34:13Z

I've fixed the path for this to be merged. To see how it behaves, see the previous CI here
https://41824-1460385-gh.circle-artifacts.com/0/html-scipyorg/index.html

tupui · 2022-01-17T19:00:36Z

doc/source/_static/version_switcher.json

+    {
+        "name": "1.9.0 (dev)",
+        "version": "dev"
+    },
+    {
+        "name": "1.8.0 (rc)",
+        "version": "1.8.0"
+    },
+    {
+        "name": "1.7.3 (stable)",
+        "version": "1.7.3"
+    },
+    {
+        "version": "1.7.2"
+    },
+    {
+        "version": "1.7.1"
+    },
+    {
+        "version": "1.7.0"
+    },


These will depends on how we fix the deployment of the live docs. Previous versions' links are resolving properly.

mattip · 2022-01-18T19:30:02Z

Yay! It is a nice feature. Maybe a subsequent PR can consider an optimal color that will blend in with the rest of the site.

tupui · 2022-01-18T19:33:42Z

Yay! It is a nice feature. Maybe a subsequent PR can consider an optimal color that will blend in with the rest of the site.

Yes totally @mattip! Joris opened pydata/pydata-sphinx-theme#566 to do this on the theme side. I would want to set the colours like I did before this (some red, orange, green which are colour deficient friendly). If we don't want to wait, we could tweak the CSS to do it.

jorisvandenbossche · 2022-01-19T20:16:19Z

After disabling CORS

Wondering, how did you do that? (I know we struggled with this while developing the feature in the upstream theme)

the JSON was not loading properly due to an extra comma at the end of the JSON. Maybe some warning would be nice here in case it fails to load the file

That could be a browser console warning?

Maybe a subsequent PR can consider an optimal color that will blend in with the rest of the site.

To be clear, the issue I opened is to have version-dependent colors, but we already added css classes to the dropdown button so you can robustly give it another color (one color for all versions).

tupui · 2022-01-19T20:54:21Z

Wondering, how did you do that? (I know we struggled with this while developing the feature in the upstream theme)

On Safari you have an option in the Develop menu. And for Chrome you can launch it from the terminal with option (be sure to close all sessions or it will just bring the current one up and not disable anything)

open -n -a /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome  --args --user-data-dir=”/tmp/chrome_dev_test” --disable-web-security

That could be a browser console warning?

Yes would be helpful I think.

... (one color for all versions).

I did not think about this point. It might look like a rainbow tree if we allow different colour for different version when you open the list. Sections might be better and maybe then just having the proper colour only for the selected version.

jorisvandenbossche · 2022-01-19T21:16:53Z

Thanks for the info on CORS disabling, that's useful :)

... (one color for all versions).

I did not think about this point. It might look like a rainbow tree if we allow different colour for different version when you open the list. Sections might be better and maybe then just having the proper colour only for the selected version.

Ah, I was actually talking about the color of the "button", not of the entries in the dropdown list. But maybe I misunderstood the original feature request about this.
I agree sections in the dropdown would be nice, but that's probably not straightforward with the current way we work with the json file to list the entries ..

[skip ci]

[skip azp] [skip actions]

[skip ci]

[skip azp] [skip actions]

[skip ci]

This reverts commit c466cc7.

[skip azp] [skip actions]

tupui · 2022-03-28T12:25:28Z

@rgommers I updated the PR. We still need to decide on the style. There are 2 customisation options: style the button when a version is selected, style the elements in the list.

Right now it renders as:

Button style is by default Blue and depending on if it's a dev, stable or old version the background is adjusted in the list (I made a typo in the css this is why dev is not orange).

I am not sure about colouring the list. It's a bit too rainbow-ish. Maybe just styling the button when a version is selected would be enough. Or we do more customisation to make it pretty but this is not my strong point 😅

In the end, maybe this would be the simplest with just a change of the button and not the list:

/* If the active version has the name "dev", style it orange */
#version_switcher_button[data-active-version-name*="dev"] {
   background-color: #E69F00;
}

/* green for `stable` */
#version_switcher_button[data-version-name*="stable"] {
   background-color: #009E73;
}

/* red for `old` */
#version_switcher_button[data-version-name*="old"] {
   background-color: #980F0F;
}

(I still need to find a way to select old versions, so we could remove "old" in the name of old versions.) EDIT: found it

What do you think?

[skip azp] [skip actions]

tupui · 2022-03-28T15:48:56Z

Ok I have it for the button, here are the results:

As you can see, for a PR we will have the default button with the PR number (this is something I added previously)

rgommers · 2022-03-28T18:22:05Z

That color scheme looks good to me, at least for now. It can always be tweaked later.

doc/source/conf.py

tupui · 2022-03-28T20:30:10Z

That color scheme looks good to me, at least for now. It can always be tweaked later.

Ok then ready on my side @rgommers @tylerjereddy

tupui · 2022-03-30T20:29:11Z

I plan to merge it on Saturday night if there are no comment since then.

* master: (632 commits) Update _dual_annealing.py (scipy#15939) TST: stats: make `check_sample_var` two-sided (scipy#15723) DOC: sparse.linalg: add citations for COLAMD DOC: fix missing comma in conf ENH/MAINT: Version switcher from the sphinx theme (scipy#15380) MAINT: stats: remove support for `_rvs` without `size` parameter (scipy#15917) BUG: Handle base case for scipy.integrate.simpson when span along the axis is 0 (scipy#15824) MAINT: stats: adjust tolerance for failing test only MAINT: stats: adjust tolerance of failing TestTruncnorm MAINT: special: Clean up C style in ndtr.c CI: remove pin on Jinja2 (scipy#15895) STY: Remove white spaces MAINT: stats: exempt gilbrat from refguide_check MAINT: stats: rename continuous_gilbrat->continuous_gibrat MAINT: stats: correct name Gilbrat -> Gibrat [ENH] circvar calculated simply as 1-R (scipy#5747) DEP: deal with deprecation of ndim >1 in bspline MAINT: stats: more specific error type from `rv_continuous.fit` (scipy#15778) DOC: fix import in example in _morestats (scipy#15900) [BUG] make p-values consistent with the literature (scipy#15894) ...

tupui added enhancement A new feature or improvement Documentation Issues related to the SciPy documentation. Also check https://github.com/scipy/scipy.org maintenance Items related to regular maintenance tasks labels Jan 7, 2022

tupui self-assigned this Jan 7, 2022

tupui requested a review from rgommers as a code owner January 7, 2022 12:21

tupui force-pushed the version_switcher branch from 7f967e4 to 000cd43 Compare January 7, 2022 13:20

tupui marked this pull request as draft January 7, 2022 13:25

jorisvandenbossche mentioned this pull request Jan 17, 2022

Allow adding extra, version-specific css classes to the version dropdown pydata/pydata-sphinx-theme#566

Closed

tupui marked this pull request as ready for review January 17, 2022 16:58

tupui added this to the 1.9.0 milestone Jan 17, 2022

tupui commented Jan 17, 2022

View reviewed changes

tupui requested a review from tylerjereddy January 17, 2022 19:00

melissawm mentioned this pull request Jan 18, 2022

DOC: Add a version selector numpy/numpy#20841

Closed

tupui mentioned this pull request Jan 19, 2022

Allow multiple url_template in version switcher pydata/pydata-sphinx-theme#573

Closed

tupui added 12 commits March 28, 2022 12:26

MAINT: configure switcher available versions

7bae510

MAINT: switcher configuration.

88f9d83

[skip ci]

MAINT: fix duplicate version in navbar

4ce2226

MAINT: update theme version and navbar conf

2f0f47b

[skip azp] [skip actions]

MAINT: fix json comma and raw url to versions

8045b74

[skip ci]

MAINT: same url_template for live and dev

c97c5bd

[skip azp] [skip actions]

MAINT: change json version configuration path

c466cc7

[skip ci]

MAINT: update version theme

85a5636

Revert "MAINT: change json version configuration path"

44f6d08

This reverts commit c466cc7.

MAINT: update url for switcher

b8a99ee

MAINT: css for version colours

15d9d1f

MAINT: fix links.

d46746c

[skip azp] [skip actions]

tupui force-pushed the version_switcher branch from d48c8cc to d46746c Compare March 28, 2022 11:21

tupui added 2 commits March 28, 2022 15:59

MAINT: remove old and change only button style.

23f9494

[skip azp] [skip actions]

MAINT: same border colour [skip ci]

2e41a34

tupui force-pushed the version_switcher branch from 06b6b29 to 2f62e9f Compare March 28, 2022 15:29

MAINT: fix dev button styling [skip ci]

c1fa6ad

tupui force-pushed the version_switcher branch from 2f62e9f to c1fa6ad Compare March 28, 2022 15:39

tupui commented Mar 28, 2022

View reviewed changes

doc/source/conf.py Outdated Show resolved Hide resolved

Update doc/source/conf.py

d7a6350

tupui merged commit 7a2ed20 into scipy:main Apr 2, 2022

tupui mentioned this pull request Apr 3, 2022

MAINT: 1.8.1 backports/prep #15926

Merged

tupui deleted the version_switcher branch May 2, 2022 16:03

tupui mentioned this pull request May 6, 2022

Version dropdown menu in local development mode pydata/pydata-sphinx-theme#647

Closed

Uh oh!

ENH/MAINT: Version switcher from the sphinx theme #15380

ENH/MAINT: Version switcher from the sphinx theme #15380

Uh oh!

Conversation

tupui commented Jan 7, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tupui commented Jan 7, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jorisvandenbossche commented Jan 7, 2022

Uh oh!

tupui commented Jan 7, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

drammock commented Jan 7, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tupui commented Jan 10, 2022

Uh oh!

tupui commented Jan 16, 2022

Uh oh!

jorisvandenbossche commented Jan 17, 2022

Uh oh!

tupui commented Jan 17, 2022

Uh oh!

jorisvandenbossche commented Jan 17, 2022

Uh oh!

tupui commented Jan 17, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tupui commented Jan 17, 2022

Uh oh!

tupui Jan 17, 2022

Choose a reason for hiding this comment

Uh oh!

mattip commented Jan 18, 2022

Uh oh!

tupui commented Jan 18, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jorisvandenbossche commented Jan 19, 2022

Uh oh!

tupui commented Jan 19, 2022

Uh oh!

jorisvandenbossche commented Jan 19, 2022

Uh oh!

tupui commented Mar 28, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tupui commented Mar 28, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rgommers commented Mar 28, 2022

Uh oh!

Uh oh!

tupui commented Mar 28, 2022

Uh oh!

tupui commented Mar 30, 2022

Uh oh!

Uh oh!

tupui commented Jan 7, 2022 •

edited

Loading

tupui commented Jan 7, 2022 •

edited

Loading

tupui commented Jan 7, 2022 •

edited

Loading

drammock commented Jan 7, 2022 •

edited

Loading

tupui commented Jan 17, 2022 •

edited

Loading

tupui commented Jan 18, 2022 •

edited

Loading

tupui commented Mar 28, 2022 •

edited

Loading

tupui commented Mar 28, 2022 •

edited

Loading