Support for loud version warning banners

[bryevdv]

For the Bokeh docs, we have an extremely loud banner warning any time a user is on either

• an old version of the docs
• a dev/rc version of the docs

This banner looks like:

A similar banner with "for a PREVIOUS version" appears when looking at an old docs version.

I know that the docs at Style the Switcher Buttons describe how the switcher entries can be customized based on version. This is great, but after ~10 years of supporting OSS projects, it is also way, way too subtle on its own :) We want a version warning that is loud and un-missable, and also has a call-to-action link to latest docs.

Currently we implement this custom banner with some custom JS:

$(document).ready(function () {
  const randid = Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15);
  $.getJSON('/switcher.json?v=' + randid , function (data) {
    if (BOKEH_CURRENT_VERSION != data[0].version) {
      let msg
      if (data.findIndex((elt) => elt.version == BOKEH_CURRENT_VERSION) < 0 ) {
        msg = "DEVELOPMENT / PRE-RELEASE"
      } else {
        msg = "PREVIOUS RELEASE"
      }
      const content = $('<div class="version-alert">This page is documentation for a ' + msg + ' version. For the latest release, go to <a href="https://docs.bokeh.org/en/latest/">https://docs.bokeh.org/en/latest/</a></div>')
      $('#banner').append(content);
    }
  })
})

However, we would like to reduce the amount of customizations that are necessary, and try to move towards only using a stock version of this theme, if possible. Adding support for some kind of loud version warning option would allow us to remove this custom JS entirely.

[jarrodmillman]

This would be useful for NetworkX as well:

We would also like one for old releases that says they are no longer supported.

[drammock]

ditto for MNE-Python:

Here is how we do it: https://mne.tools/versionwarning.js

[choldgraf]

Some quick questions:

• Would announcement banners be enough for this? Or is this better as a new type of banner that goes under the header?
• One simple option could be to use the announcement banner option, and add a check on Python for "if version == xxx, then active the announcement banner feature w/ a custom message"

[bryevdv]

I only put our banner under the header because hell is CSS and that's the best I could manage before giving up on trying to put it above. That said, I think either location is fine. But I do think this is distinct from an announcement. E.g. a fundraising or user survey announcement should appear in addition to a version warning on non-latest versions.

[choldgraf]

Right so that would be the one downside - you'd use it instead of other announcement text, so you couldn't have both the announcement text and the warning banner up at the same time. Would that be a big problem?

Conversely, I am trying to understand if having a dedicated warning banner would be better, but where you can't change it to anything other than the same warning message across all documentation (e.g. "WARNING: You're on an outdated version, click this button for the latest" or something)

[bryevdv]

Is personally prefer a dedicated version warning banner (that accommodatels old as well as pre-release versions).

[drammock]

I agree that version warnings need/deserve a dedicated banner. For example, ours has some JS that tries to make the link go to the corresponding docs page in the stable version (like what the version-switcher dropdown does). That feature is, I think, something other sites would like too, and something that isn't relevant for the general-case announcement banner.

[QuLogic]

We do a similar thing in Matplotlib, but it's generated by a script so we can have the redirects point to the same path in the new docs if they're available.

[choldgraf]

There's an implementation of this that got pretty close but got bogged down in smaller details and then I lost time to work on it. But maybe it would be useful for others to pick up or in case I have more time to try again in the future:

• https://github.com/pydata/pydata-sphinx-theme/pull/780

[12rambau]

Is it solved by https://github.com/pydata/pydata-sphinx-theme/pull/1354 ?

[drammock]

closed by #1354