Version warning bar for development part of the documentation

[AlenkaF]

The new released version of the theme is 🔥
Thank you so much for working on it and adding all the cool stuff!

I have a suggestion regarding the new version warning bar that I know would concern Arrow and Pandas project. Maybe others also have a similar situation.

In Arrow, we are referring to the stable version of the docs for all cases except the development part. In the case of the development section, the preferred version of the docs is actually the unstable version. This helps eliminate errors when working on the source code in case of bigger changes in the workflow.

See

• https://arrow.apache.org/docs/developers/contributing.html
• https://arrow.apache.org/docs/12.0/index.html
• https://github.com/apache/arrow/blob/main/docs/source/_static/versionwarning.js

We will use the version warning bar added to the 0.14.0 release of PyData Sphinx Theme (with Arrow 14.0.0 release) and would like to open up a discussion to see if the support of a separate banner text for the developers sections of the documentation is feasible.

[drammock]

this is a good idea, but a tricky one to generalize I think. Some thoughts:

1. allow to restrict which pages get a version warning message (presumably regex on the page filenames or URLs). That I think should be relatively straightforward.
2. allow instantiating multiple version warning bars (presumably with non-overlapping regexes for which pages they should appear on, though in principle it would be possible to display 2 warning bars on one page). That also seems possible but a little trickier.
3. allow the "target version" to be different for the multiple requested warning bars. We currently draw the "preferred version" from the version switcher JSON source, and thus there is no way to specify different preferred versions for different instantiations of the warning bar. So there would need to be a new parameter for the warning-bar-generating code that let the user optionally pass in an override value for which version should be considered "preferred".

This idea may not fly, but what about combining (1) above (so that dev-site dev-related pages don't get a version warning) with a change to your site where all the dev-related pages in old or stable versions of the docs become automatic redirects to the dev version? It's... inelegant? ... in that it means rewriting history (effectively deleting the older versions of those pages) and it means users might get switched from stable to dev without realizing it, just by clicking on the dev docs. So maybe that's a non-starter.

Anyway, I think items 1-3 above are all possible, and could probably be addressed in 3 separate PRs, so you (or someone else) could start chipping away at them as soon as the opportunity arises.

[AlenkaF]

Thank you so much for showing interest and providing ideas!
We have been thinking something in the line of item 3 from you list - adding an additional "preferred" label like "preffered_dev" or similar which would hold for the dev docs. Also it would have to be made clear which part of the docs is the dev section.

The separation of the work in three different PRs is a great idea!

There is a release coming up for Arrow so I will be a bit quiet for now. But I do plan to have a go at this after (unless somebody else starts with it before).

[jorisvandenbossche]

but a tricky one to generalize I think.

It might also depend to what extent we would want to generalize it? Do we want to fully generalize the notion of each version of the docs being able to point to its own preferred version depending on the subsection of the documentation you are looking at? Or are we fine with "just" harcoding the idea of allowing one more preferred version for the dev docs?

Because if we would go with the minimal (specific to dev docs) idea, I think we essentially only need two pieces of information: indicate in the json file which is the dev version (eg in addition to the "preferred": true, add "dev": true or "unstable": true to another entry in the json file), and then in conf.py you need to provide a way to define the subsection of the docs that would need this other warning (i.e. your point 1; for the Arrow example, this is a subdirectory, so a simple string match would work).

I suppose the question is: is this dev docs a typical scenario? Or do we think that other sites will have similar needs to tweak the warning but for other cases? (in which case actually generalizing might be nice)

[drammock]

It might also depend to what extent we would want to generalize it? Do we want to fully generalize the notion of each version of the docs being able to point to its own preferred version depending on the subsection of the documentation you are looking at? Or are we fine with "just" harcoding the idea of allowing one more preferred version for the dev docs?

One other use case I can think of is for packages that have a major version bump and are maintaining 2 different APIs in parallel --- there might be some pages where you want to say "see version N docs" and others where you want to say "see version N+1 docs". It's still only 2 versions... but calling one "preferred" and one "dev" is not reflective of the use case. My number (3) suggestion above would I think accomodate both this case and Arrow's needs.

That said, I'm inclined to accept whichever approach someone is willing to code up, as I likely won't have time myself to add this feature any time soon (at least, not in what remains of 2023). Especially given that my use case is imagined, whereas the Arrow use case is real --- if it turns out to be easier to just add and act on a new JSON value feel free to take that approach. Either way would be an improvement.

[FranzRoters]

Just realized, that this is potentially related to issue #1909 opened by myself. It is about being able to change the text diaplayed by the version warning banner. So, if someone finds time to implement something, it might be possible to takle both issues in a combined way.

[adrinjalali]

Just ended up here from scikit-learn/scikit-learn#30242, to mention we're missing the same thing in scikit-learn.