Script to warn when viewing version other than stable #13
Conversation
|
I think the wording and styling could benefit from some improvements. But because it's not embedded in the HTML, some of that can be improved over time. |
There was a problem hiding this comment.
This is quite nice! The warnings I was mentioning is for instance https://flask.palletsprojects.com/en/1.0.x/ there it's done by statically injecting this header into HTML by ReadTheDocs as far as I can tell.
I like that it's single JS file used everywhere that we can always change later. One limitations is that web crawlers may not see it if they don't render JS, but I guess we already have a link in the menu to the stable docs so that should be enough.
One caveat is that we need to remember to re-run the sed script for any commit on the released branches. I think we should add it on the CircleCI deploy job for non master branches.
| showWarning('You are looking at documentation for an old release of ' + | ||
| 'Scikit-learn (version ' + versionPath + '). Try the ' + | ||
| '<a href="https://scikit-learn.org">latest release</a> or ' + | ||
| '<a href="https://scikit-learn.org/dev">development</a> ' + |
There was a problem hiding this comment.
I am not sure for putting the dev on outdated versions. Few users need it and it can lead to confusion.
There was a problem hiding this comment.
hmm, the dev version would be nice if we also tell people that they can have it through the nightly wheels. We would also get more testers before the release that way. I wouldn't mind that.
There was a problem hiding this comment.
Do you mean that the warning shown on dev should point the user to installation instructions? Nice idea
There was a problem hiding this comment.
I agree with @rth about not strictly encouraging the dev docs. Maybe we can make it clearer with
Try the latest stable release (recommended) or the development version (unstable).
And yes linking to installation instructions on the dev version would be great too
|
Do you want to run the sed command in this PR or a separate one? |
|
I tried including the sed in this branch but my web browser was a bit
overwhelmed by the diff. I think we'll do that without a pr :D
In fact, I have another branch open with that change.
I think there are several improvements that can be made here. For example a
JavaScript fetch could confirm whether an equivalent page exists in stable
and link directly to that. We could have a more complete version switcher.
I think here we mostly need to decide if this is an acceptable first
iteration. Does the dev warning look too much like the old version warning?
|
|
Updates:
|
|
Nice, I like this one, shall we merge? |
+1, I haven't reviewed the JS but I like the messages too |
|
Now live on non-dev versions. https://scikit-learn.org/0.20/ |
| 'font-size: 1.5em', | ||
| 'border: 1px solid red', | ||
| 'background: pink', | ||
| 'width: 100%', |
There was a problem hiding this comment.
This specific line makes the box non mobile-phone friendly (it creates a horizontal scroll by extending out of the viewport). It is not needed.
There was a problem hiding this comment.
I opened the following PR to address this problem: #14
This script would be available to work with the following change to all HTML files here:
It produces banners like the following on the dev version:
and the following on older versions:
Inserting the script would be done in another PR, and as a change in our Circle CI doc deployment.
To do after merge: