Add a version menu to the Sphinx build

[asmeurer]

To make this work, we need to add a versions.json file to the root of the gh-pages branch that looks like

{
   "label": "target"
}

Where label is the text label for the version and target is the name of the directory containing that version.

Right now, without that, it will just say "No versions found".

[asmeurer]

For example, here is the json for https://www.statsmodels.org/

https://github.com/statsmodels/statsmodels.github.io/blob/master/versions-v2.json

We should also add a simple index.html with a redirect to "stable" or whatever at the root so that https://data-apis.org/array-api/ works.

[rgommers]

To make this work, we need to add a versions.json file to the root of the gh-pages branch that looks like

Wouldn't we want to check in that file, like _static/versions.json is suggesting?

Where label is the text label for the version and target is the name of the directory containing that version.

So the downside is that with this approach you cannot use a "normal" branching/tagging scheme to manage releases, you really have to copy over all files. And then things like cherry-picking won't work either, you have to manually copy-paste between versions if there's some fix you want to apply to older versions. And you may have to rebuild multiple versions?

Did you think about making this work with a regular git repo release flow, where we create a 2021 branch when we're ready to release that version?

[rgommers]

This looks like it's going to be a continuous source of friction. Not a blocker for this PR, but can't we just turn off this cross-linking?

[asmeurer]

If you know how to do it let me know. When I looked there didn't seem to be a way.

[asmeurer]

@rgommers I think you might be confusing the sources with the deployed HTML. With this model, the sources do only have one branch (main), which gets tagged. The only reason you would ever branch off is if you want to backport something to an older release. The docs never get copied.

The deployed branch (gh-pages) is where things are duplicated. This is basically expected. If you want https://data-apis.org/array-api/2021.01/ and https://data-apis.org/array-api/development to be separate versions, the way that you have to do that, as long as you are using a static site host like GitHub pages, is to have two directories 2021.01 and development in the gh-pages branch, which contain the respective HTML files. There may be duplication among those files if the content is identical, but it's not a concern because no one should ever edit those files directly. If you want to make a change, you go to the relevant sources branch and make the edits there, then redeploy the built HTML from that.

The versions.json file lives in gh-pages, alongside the different directories 2021.01, development, etc. This is necessary because it lets us update the list of versions when a new version is released without having to rebuild the previous versions. The version menu in the previous versions will always read from the single versions.json to get the full list of versions (the only downside to this is it requires Javascript and won't show up in local builds, but that's not a huge problem).

I don't really see any benefit to storing versions.json in main as well, as it would just have to be copied over to gh-pages. It would only create confusion, because there should only ever be a single versions.json across all versions, but storing it in the sources branch means there is a different version of the file in every branch/tag.

[asmeurer]

By the way, we can merge this now, before tagging the release. The actual version metadata goes in the versions.json in the gh-pages branch, which can be updated separately. So we can merge this now and add a versions.json with just a single "dev" version for now.