Provide docs for multiple versions

[prjemian]

PyData provides a dropdown version selector in the header of each page using a JSON catalog of versions available: switcher.json. A search of the source repository provides indications how the feature is supported.

Originally posted by @prjemian in #712 (comment)

[prjemian]

This discussion is relevant: pydata/pydata-sphinx-theme#1013

[prjemian]

Documentation of switcher.

[prjemian]

Looking for suggestions how to implement the cache of previous documentation versions (with efficiency so that old docs are not rebuilt repeatedly). And yet the cache of older documentation does not grow indefinitely.

[prjemian]

Also, consider adding a loud banner when looking at any unreleased docs, such as bokeh.

[prjemian]

Numpy is a package that manages its documentation sets outside of RTD. It provides old versions on a separate page rather than a dropdown.

Circle CI manages the cache of old documentation versions.

[prjemian]

One idea: upload release artifacts

[prjemian]

https://stackoverflow.com/questions/59998584/github-actions-deploy-artifacts

[prjemian]

https://github.com/marketplace/actions/upload-a-build-artifact

[prjemian]

First part of the numpy switcher file:

[
    {
        "name": "dev",
        "version": "devdocs",
        "url": "https://numpy.org/devdocs/"
    },
    {
        "name": "1.24 (stable)",
        "version": "doc/1.24",
        "url": "https://numpy.org/doc/stable/"
    },
    {
        "name": "1.23",
        "version": "doc/1.23",
        "url": "https://numpy.org/doc/1.23/"
    },
    {
        "name": "1.22",
        "version": "1.22",
        "url": "https://numpy.org/doc/1.22/"
    }
]

[prjemian]

The JSON file needs to be at a stable, persistent, fully-resolved URL

such as ROOT/docs/source/_static/switcher.json

-- https://github.com/pydata/pydata-sphinx-theme/blob/3ee5fcab93b3cf2eb8a18b6b0b5f4b30aaf9bb3b/docs/user_guide/version-dropdown.rst#L75