Keep older versions of the spec in the repo's `HEAD`

[honno]

Currently versioning in our docs works building pages for released versions (i.e. just 2021.12 for now) a final time, to be linked to later. So in the gh-pages branch, you have the 2021.12/ folder unchanged after we tagged this repo with 2021.12, and a draft/ folder which now gets updated along this repo. It makes sense for projects to do this and seems an ubiquitous practice, as you rarely want to care about modifying older docs.

I was wondering however if we'd want to take a different approach: docs for every released version of the spec always live in the repo's HEAD, alongside the draft. Such an approach would certainly have us have a separate stubs folder/sub-module, e.g.

.
  spec/
    ...
    API_specification/
      ...
      array_api/
        draft/
          __init__.py
          _types.py
          _array_object.py
          ...
        2021.12/
          __init__.py
          _types.py
          _array_object.py
          ...

and probably will require separate folders for the rest of the RST in ./spec/API_specification, depending on how you go about things.

The advantage to this comes back to "caring about modifying older docs"—a spec standard probably does care more about "backports" than your typical software package. Currently we can't backport non-API changes to our 2021.12 docs, where it'd be nice to include clarifications and other niceties such as:

• Add self param to array object properties #464
• Include __array_api_version__ in API specification section #480
• PR: Rename signatures module to array_api #430 (i.e. it would be nice to keep urls and intersphinx-refs consistent accross versions)

Another advantage is if we want to release the stubs as a package (#411), where @asmeurer bought up the idea of keeping older versioned stubs in the repo so we could just publish the spec as-is on PyPI #472 (comment). Package or not, having the stubs of past versions live on HEAD is useful for the compliance suite too.

All in all, this might not be a big deal? And I do see value if the docs for a released version are immutable.

I raise this issue so folks can 1) identify any glaring issues with my thought process here 2) see if there's even a desire. Ideally I'd just implement this first for us to look at, but having a little play around this might be a bit non-trivial to actually implement.