-
Notifications
You must be signed in to change notification settings - Fork 317
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
NEW: Add version warning banners #780
Conversation
This comment was marked as resolved.
This comment was marked as resolved.
@choldgraf This looks nice, a couple of comments:
Selenium is probably your best bet |
Would it be safe to make these assumptions?
If so, then I don't think the logic you mention would be too tough. What I want to avoid is lots of new config surface area because every variable can lots of different spellings etc. But I'm not sure whether all of these assumptions hold for all of the stakeholder projects we care about 🤔 |
I might be misunderstanding of some aspect of how the switcher works. I don't really understand what this is asking. If this is about what dev version strings look like, the can have either "dev" or "rc". I imagine it is harder to reliably discern pre-releases in JS, without
It doesn't matter to me what terminology is used in configuration, but we have used I guess I should try to understand better how the PST switcher functions, and how a page can determine if it is "not stable". How do PST pages "know" what version they are for? Do they pull it out of the page's URL? Or is there a |
On MetPy we haven't yet switched to the built-in version selector (we're on an old one). We check against |
That sounds exactly how we do it with Bokeh except I was not aware of |
Hmmm - what about a system like:
|
This would work, but it also seems somewhat more difficult to maintain. Updating now requires finding the old preferred and deleting it, and then adding preferred to the new block. And what happens if two or more blocks accidentally specify preferred at the same time? I guess that might be the only option without changing the top-level structure of Re: oudated vs unreleased, I should have not mentioned it :) I think it's best to not worry about it and just have a combined banner message with link (as I mentioned we have "rc" pre-releases in addition to "dev"... absent a reliable way to determine pre-releases it seems to fragile to worry about) |
yeah - I guess the other approach we could take is to let the
and to avoid a breaking change the logic could be "if |
@choldgraf I personally think that would be a good (forward-looking) change but I'm also only thinking about the benefits, not any costs :) Obviously that's something for the PST team to weigh |
I mean, I think that in general having the top-level structure of the JSON file be a |
@choldgraf I'll just state that we're generating our json file with every major doc release automatically: https://github.com/Unidata/MetPy/blob/gh-pages/versions.json |
Could you (or others) share your opinion on what seems like an intuitive and hassle free config structure to trigger other kinds of behavior like "direct people to version X"? Does my proposal above seem to make sense? |
Hmmm, thinking about this more: I think that the simplest path forward would be to leave the configuration as, is, but introduce two optional keys per entry:
Then the logic would be:
So as a maintainer, you would need to:
At least this way the only configuration changes are in the one I just pushed a commit that shows off this behavior, and updates the docs |
Just speaking for myself, this would increase the amount of manual work past the value of shedding our template customizations, and I would just keep the system we have in place presently. |
@bryevdv I'm a bit confused - with the current system, you have to manually add new versions to the JSON when a new version is released. It doesn't seem like this is any more work than what you'd already have to do. Maybe you are using the {
"name": "dev",
"version": "latest",
"description": "the development version",
"url": "https://pydata-sphinx-theme.readthedocs.io/en/latest/"
},
{
"name": "0.9.0 (stable)",
"version": "stable",
"preferred": "true",
"url": "https://pydata-sphinx-theme.readthedocs.io/en/stable/"
},
{
"name": "0.8.1",
"version": "v0.8.1",
"url": "https://pydata-sphinx-theme.readthedocs.io/en/v0.8.1/"
}, to this:
That said, if folks in general think it is too much manual work/toil to change 1 line of the JSON file each time there's a release, then I don't think we'll be able to incorporate this feature in a project-agnostic way. Do others agree this would be too much work? If everybody is just going to continue maintaining their own custom templates we can just close this one. |
The issue for me is that rather than simply adding or replacing a line (even a block), which is something I might consider automating, I'd have to find the old block in which a previous release was marked preferred, and edit/delete it to remove the preferred flag as well. This seems fragile since it seems like it would be trivially easy to accidentally mark or leave two or three release blocks as preferred unintentionally, resulting (I assume) in undefined behavior. In order to prevent that, we'd have to add some kind of specialized linter to check that only a single block is marked "preferred", so now we are developing new tooling as well. This is why I think having a single explicit field like
Given that projects do seem to have their own unique requirements around versions, perhaps a more approachable goal would be to simply offer a consistent mechanism to add/populate a warning banner below the menu from JS (with whatever content is appropriate for their project). |
I wonder if you are using a different naming strategy than this theme uses. In the example I gave above, the "preferred" version is always the entry named So for example, here's a GIF of the changes that would need to be made when we released a new version, note that |
@choldgraf I do think we have some terminology differences. But I was able to distill the important difference to this I think: The theme seems to assume that the "latest" version does not also get its own "x.y.z" link. But for us, if Bokeh 4.3.7 is the latest release, then both of these links will work, and both should not have the warning banner:
And I just don't see how that is feasible unless the page can compare its actual package version. I.e. compare "4.3.7" which is the value of It's clear that I thought this was going to be a simple ask, but it's also clear that it has not turned out to be. :) It's definitely fine with me if you want to close this and the issue, because I did intend for things to spin out to so much work/discussion. |
Hmmm ok. So just to confirm, you think that this problem would go away if the configuration could be something like: {
"preferred": "<some-version",
"versions": [<list-of-versions>],
} Where |
@choldgraf if we have this:
then assuming:
then yes. |
Well in our case we'd check for the I opened an issue about changing the configuration structure to see if others had thoughts pro/con here: |
I guess this value gets injected into the rendered page analogous to |
Yeah - though now I'm wondering if we should just use DOCUMENTATION_OPTIONS instead. How does that get populated? |
I believe it is specifically the value of |
Adds a a warning banner to be shown on non-stable versions of the docs. Inspired by pydata/pydata-sphinx-theme#780
superceeded by #1335 |
This adds functionality in our version switcher logic to add a warning banner directing users to a different version if they are not on a specific version of the documentation.
It uses a placeholder ID in our theme template that comes just after the header navigation bar, and adds some JavaScript to the version switcher logic that looks for this placeholder and appends the warning banner just after
I'm not really sure how to test this one, since basically all the functionality is in JavaScript...
closes #759