Prior versions of the docs should link to more recent versions of the docs

[Eric-Arellano]

It's easy to look at old versions of the docs without realizing there are newer versions.

Our previous versions sidebar only shows prior versions, not new ones:

Fixing this will be tricky because we currently don't rebuild the docs for prior versions. I suspect we don't want to, such as risk of bit rot meaning that the docs rebuild will fail. I'm curious if we can dynamically pull the version info rather than hardcoding it. For example, have a simple API that all versions of the docs can hit to determine the versions to show.

Ideally, we can also have a warning when you are not on the latest version of the docs.

[mtreinish]

This was something we discussed at the time we added the old version builds. The idea I proposed at the time was generating a JSON file as part of the current release's builds that contains a stable version list and then have the theme pull that json file from a relative path to generate the links. At the time though there wasn't sufficient bandwidth to look into doing that so we just used the git tag list and parsing that's used now.

[coruscating]

For newer builds, we can add code to generate the warning to experimental-bundled-ui-shell.js since it can be dynamically updated, right? If there isn't something equivalent in the older docs, maybe we can write something to crawl the directories and add a load external javascript line to every page without rebuilding the docs.

[Eric-Arellano]

since it can be dynamically updated, right?

We decided this week to move away from web components always using the latest version automatically. Instead, we'll update web components manually. See #274 for the motivation.

The idea I proposed at the time was generating a JSON file as part of the current release's builds that contains a stable version list and then have the theme pull that json file from a relative path to generate the links.

That sounds great.

maybe we can write something to crawl the directories and add a load external javascript line to every page without rebuilding the docs.

We would use JavaScript to dynamically populate the list by e.g. reading the JSON file that Matthew proposed. See https://github.com/ParkingReformNetwork/parking-lot-map/blob/19ff1830ec27cf8bf95fa22bdb32e976539687a0/src/js/setUpSite.js#L47-L60 for an example of how JavaScript lets you do that in a volunteer web dev project I help with

[javabster]

Another idea to throw into the mix:

we could update the web component top menu to check the current website url. If the url is not the latest version (i.e. does it have documentation/stable in it) then it could show an additional button/banner/warning that says something like "you're reading an outdated version of the Qiskit Docs, click here to go to the latest version"

a couple of quick design options:

[Eric-Arellano]

we could update the web component top menu to check the current website url. If the url is not the latest version (i.e. does it have documentation/stable in it) then it could show an additional button/banner/warning that says something like "you're reading an outdated version of the Qiskit Docs, click here to go to the latest version"

This is a great idea. This feature would still be useful to add for ecosystem sites, which have shown interest in this mechanism.