Keep documentation for previous spec versions alongside draft

[honno]

WIP PR to resolve #488. This PR keeps the source of the 2021.12 spec in the HEAD commit of the repo, which is important for backporting features and cross-version tooling (i.e. array-api-tests).

Note on the diff: it's bloated by having soft-duplicated the docs/stubs so we can have 2021.12 and draft versions. Importantly files for both versions preserve their history (solution used), so you can git blame the 2021.12 files like they were on release day. The bloated diff otherwise seems inevitable, as git (or at least GitHub) can't mark multiple files as renamed, even if there are no changes to either file 😕

It won't be up-to-date but you can check https://honno.dev/array-api/ for rendered docs. I've also updated live previews, but that won't work for this PR as it requires the default branch to be updated too (does work for honno/array-api).

What this PR changes

This introduces a module array_api_stubs which holds the signature stubs of all versions, which lives in src/ and can be installed via pip install .. Currently you can see in the main branch only draft stubs are available, living in spec/API_specification/array_api (this PR moves them to src/array_api_stubs/_draft/).

To hold the non-docstring documentation of all versions, spec/ now contains technically separate Sphinx docs for each version in respective folders (i.e. spec/2021.12/ and spec/draft/). Sphinx configuration is however mostly shared, as each conf.py imports the same _array_api_conf module, i.e.

# spec/draft/conf.py
import sys

from array_api_stubs import _draft as stubs_mod
from _array_api_conf import *

release = "DRAFT"
sys.modules["array_api"] = stubs_mod
# EOF

The main drive in having technically separate docs is to keep utilising Sphinx's autodoc, which is incredibly useful but ill-equipped of having multiple spec versions in the repo. The ability to monkey-patch sys.modules in the conf.py of every version-doc gives us consistency, basically just so we don't have to worry about modifying the .. currentmodule targets for every version.

Building the spec website is now fully reproducible locally via the introduced make build command (I wrote a quickstart for building the spec in README.md). Before we would just update the current version folder in gh-pages, which is sensible for most docs, but feels a bit loosey-goosey if we want the ability to backport things and generally it's nice to build the whole website locally. The pages workflow now works with pip install .[doc] and make build, but I have yet to update the preview workflow. sphinx-(auto)build will still serve us well when working on just the draft version.

TODOs

• Preserve git history for 2021.12 spec/stub files
• Working site previews again
• Remove temporary commits (namely used to bypass CI workflow restraints)
• Document procedure on spec releases

(So beware, there's going to be a fair few force-pushes here.)

Follow-up PRs

First point of order is known backport candidates. On the top of my head:

• PR: Rename signatures module to array_api #430 had to be backported for this PR to work, so follow-up should be redirecting signatures.<file>.* to respective array_api.* urls, just for the 2021.12 spec so links don't break.
• Add self param to array object properties #464
• Include __array_api_version__ in API specification section #480

And then I would want the package to actually be useful by tooling, notably array-api-tests—see #472 for what I've already worked on in this regard. Another PR could automate releases (probably CalVer'd) anytime a workflow detects the package has changed (inspired by Hypothesis here, and for our purposes should be simple). I've already upload the package to PyPI as array-api-stubs (just to park it), so any consortium member who's interested, feel free to ask me to make you a collaborator on PyPI.

Also, CircleCI doesn't handle that index.html magic that happens when you go to "folder" URL, i.e. https://output.circle-artifacts.com/output/job/kfc/artifacts/0/_site/latest/ won't redirect to .../index.html and so give us a seamless preview when checking non-draft versions. Generally site previews seems to be an unintended but popular use of artifacts (related discussion). A way to handle this, probably by making the version jumping explicitly suffix hrefs with index.html, would be nice.

---

So that's broad strokes. Obviously lots of little details but I didn't want to make the PR body an automatic TL;DR heh... hopefully those details speak to themselves, so if not I have/should/will be writing documentation (ofc still working on this PR). Both excited and terrified to hear what folks think 😅

[asmeurer]

I would add a README to the spec directory explaining how the layout works and what steps need to be taken to make a spec release (if there are a lot of them, maybe it could be put into a script). Also, make sure we do test making a release to make sure everything works.

[rgommers]

Let's hold off on this refactor until the changes to the standard that modify content (new functions, keywords, etc.) are done for v2022. Then we'll have a period of doing all these larger refactor/reshuffle PRs before finalizing v2022.

[honno]

Alright, I'll need to sleep on it but I think I'm happy with this PR. It was kind of a nightmare getting this PR updated post the 2022.12 release—namely because typical rebase/merge workflows completely broke down with an already magic'd git history—but I think it's now up-to-date. I'm more confident now on these git things, but I'd appreciate if there was a freeze for merging other PRs until this one gets through, assuming we're close enough to merging 😅

[kgryte]

Overall, looks good. I reviewed each file. A few minor nitpicks/questions.

I'll leave it to you, @honno, to address, as may depend on what sort of Git magic is required. Additionally, would be good to know whether merging this PR requires any special consideration (e.g., whether we can squash commit or not).

[honno]

as may depend on what sort of Git magic is required.

In case there's anything else, it should be fine to push commits on this PR, only the history shouldn't be changed without consideration.

Additionally, would be good to know whether merging this PR requires any special consideration (e.g., whether we can squash commit or not).

Yeah this can't be squashed in as it would break the preserved blame history. Either "Create merge commit" (i.e. the default for repos unless modified in settings) or "Rebase and merge" will be fine.