Keep documentation for previous spec versions alongside draft

.circleci/config.yml

@@ -19,10 +19,10 @@ jobs:
           name: build docs
           no_output_timeout: 25m
           command: |
-            pip install -r requirements.txt
-            sphinx-build -b html -WT --keep-going spec build/draft -d doctrees
+            pip install .[doc]
+            make
       - store_artifacts:
-          path: build/draft
+          path: _site/
 
 workflows:
   version: 2

.github/workflows/pages.yml

@@ -76,22 +76,14 @@ jobs:
       # Install dependencies:
       - name: 'Install dependencies'
         run: |
-          pip install -r ./requirements.txt
+          pip install .[doc]
 
       # Generate the documentation:
       - name: 'Build documentation'
         run: |
           # Turn warnings into errors and ensure .doctrees is not deployed:
-          sphinx-build -b html -WT --keep-going spec build/draft -d doctrees
-
-      # Upload the build artifact:
-      - name: 'Upload build artifact'
-        uses: actions/upload-artifact@v2
-        if: ${{ github.event_name == 'pull_request'}}
-        with:
-          name: html
-          path: build/
-          if-no-files-found: error
+          export SPHINXOPTS="-b html -WT --keep-going -d doctrees"
+          make
 
       # Configure Git:
       - name: 'Configure Git'
@@ -107,10 +99,10 @@ jobs:
           git checkout gh-pages
         timeout-minutes: 5
 
-      # Copy build artifact:
-      - name: 'Copy build artifact'
+      - name: 'Copy build to root'
         run: |
-          rm -rf ./draft && cp -R ./build/draft ./draft
+          cp -R ./_site/* .
+          cp ./_site/.gitignore .
         timeout-minutes: 10
 
       # Commit changes to:

.github/workflows/preview.yml

@@ -11,6 +11,6 @@ jobs:
         uses: larsoner/circleci-artifacts-redirector-action@master
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
-          artifact-path: 0/build/draft/index.html
+          artifact-path: 0/_site/draft/index.html
           circleci-jobs: build_page
           job-title: Check the rendered docs here!

.gitignore

@@ -22,12 +22,15 @@
 # SOFTWARE.
 #/
 
-spec/_build/
+_site/
 doctrees/
 build/
 .vscode/
 node_modules/
 __pycache__/
 *.pyc
 spec/**/generated
-tmp/
+tmp/
+*.egg-info/
+*.egg
+dist/

MANIFEST.in

@@ -0,0 +1,3 @@
+exclude README.md
+exclude src/_array_api_conf.py
+include PACKAGE.md

Makefile

@@ -0,0 +1,23 @@
+# You can set these variables from the command line.
+SPHINXOPTS    ?= -W --keep-going
+SOURCEDIR     = spec
+BUILDDIR      = _site
+
+.PHONY: default clean build
+
+default: clean build
+
+clean:
+	-rm -rf $(BUILDDIR)
+	-find . -type d -name generated -exec rm -rf {} +
+
+build:
+	-mkdir -p $(BUILDDIR)
+	-cp "$(SOURCEDIR)/_ghpages/_gitignore.txt" "$(BUILDDIR)/.gitignore"
+	-cp "$(SOURCEDIR)/_ghpages/versions.json" "$(BUILDDIR)/versions.json"
+	-cp "$(SOURCEDIR)/_ghpages/index.html" "$(BUILDDIR)/index.html"
+	-touch "$(BUILDDIR)/.nojekyll"
+	-sphinx-build "$(SOURCEDIR)/2021.12" "$(BUILDDIR)/2021.12" $(SPHINXOPTS)
+	-sphinx-build "$(SOURCEDIR)/2022.12" "$(BUILDDIR)/2022.12" $(SPHINXOPTS)
+	-cp -r "$(BUILDDIR)/2022.12" "$(BUILDDIR)/latest"
+	-sphinx-build "$(SOURCEDIR)/draft" "$(BUILDDIR)/draft" $(SPHINXOPTS)

PACKAGE.md

@@ -0,0 +1,9 @@
+# Stubs for the array API standard
+
+Documentation specific to singular Python objects in the spec (i.e., functions,
+methods and attributes) are in fact represented by stub objects in the package
+`array-api-stubs`. These stubs ultimately get rendered via the autodoc
+capabilities in Sphinx.
+
+TODO: describe how `array-api-stubs` can be used for tooling, once it actually
+has the capacity to do so.

README.md

@@ -15,6 +15,122 @@ These are relevant documents related to the content in this repository:
 See [CONTRIBUTING.md](CONTRIBUTING.md) for how to go about contributing to
 this array API standard.
 
+
+## Building docs locally
+
+The spec website is comprised of multiple Sphinx docs (one for each spec version),
+all of which exist in `spec/` and rely on the modules found in `src/` (most
+notably `array_api_stubs`). To install these modules and the additional
+dependencies of the Sphinx docs, you can use
+
+```sh
+$ pip install -e .[doc]  # ensure you install the dependencies extra "doc"
+```
+
+To build specific versions of the spec, run `sphinx-build` on the respective
+folder in `spec/`, e.g.
+
+```sh
+$ sphinx-build spec/draft/ _site/draft/
+```
+
+To build the whole website, which includes every version of
+the spec, you can utilize the `make` commands defined in `spec/Makefile`; e.g.,
+
+```sh
+$ make
+$ ls _site/
+2021.12/  draft/  index.html  latest/  versions.json
+```
+
+
+## Making a spec release
+
+The Sphinx doc at `spec/draft/` should be where the in-development spec resides,
+with `src/array_api_stubs/_draft/` containing its respective stubs. A spec
+release should involve:
+
+* Renaming `src/array_api_stubs/_draft/` to `src/array_api_stubs/_YYYY_MM`
+* Renaming `spec/draft/` to `spec/YYYY.MM`
+* Updating `spec/YYYY.MM/conf.py`
+
+  ```diff
+  ...
+  - from array_api_stubs import _draft as stubs_mod
+  + from array_api_stubs import _YYYY_MM as stubs_mod
+  ...
+  - release = "DRAFT"
+  + release = "YYYY.MM"
+  ...
+  ```
+
+* Updating `spec/_ghpages/versions.json`
+
+  ```diff
+  {
+  +     "YYYY.MM": "YYYY.MM",
+  ...
+  ```
+
+* Updating `Makefile`
+
+  ```diff
+  ...
+  	-sphinx-build "$(SOURCEDIR)/PREVIOUS.VER" "$(BUILDDIR)/PREVIOUS.VER" $(SPHINXOPTS)
+  + 	-sphinx-build "$(SOURCEDIR)/YYYY.MM" "$(BUILDDIR)/YYYY.MM" $(SPHINXOPTS)
+  - 	-cp -r "$(BUILDDIR)/PREVIOUS.VER" "$(BUILDDIR)/latest"
+  + 	-cp -r "$(BUILDDIR)/YYYY.MM" "$(BUILDDIR)/latest"
+  ...
+  ```
+
+These changes should be committed and tagged. The next draft should then be
+created. To preserve git history for both the new release and the next draft:
+
+1. Create and checkout to a new temporary branch.
+
+  ```sh
+  $ git checkout -b tmp
+  ```
+
+2. Make an empty commit. <sup>This is required so merging the temporary branch
+   (4.) is not automatic.</sup>
+
+  ```sh
+  $ git commit --allow-empty -m "Empty commit for draft at YYYY.MM "
+  ```
+
+3. Checkout back to the branch you are making a spec release in.
+
+  ```sh
+  $ git checkout YYYY.MM-release
+  ```
+
+4. Merge the temporary branch, specifying no commit and no fast-forwarding.
+
+  ```sh
+  $ git merge --no-commit --no-ff tmp
+  Automatic merge went well; stopped before committing as requested
+  ```
+
+5. Checkout the `spec/draft/` files from the temporary branch.
+
+  ```sh
+  $ git checkout tmp -- spec/draft/
+  ```
+
+6. Commit your changes.
+
+  ```sh
+  $ git commit -m "Copy YYYY.MM as draft with preserved git history"
+  ```
+
+You can run `git blame` on both `spec/YYYY.MM` and `spec/draft` files to verify
+we've preserved history. See this [StackOverflow question](https://stackoverflow.com/q/74365771/5193926)
+for more background on the approach we use.
+
+<!-- TODO: write a script to automate/standardise spec releases -->
+
+
 ## Contributors ✨
 
 Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "array-api-stubs"
+version = "0.0.2"
+description = "Stubs for the array API standard"
+authors = []
+license = {file = "LICENSE"}
+readme = "PACKAGE.md"
+requires-python = ">=3.8"
+keywords = []
+classifiers = []
+
+[project.urls]
+Source = "https://github.com/data-apis/array-api/"
+Documentation = "https://data-apis.org/array-api/"
+Homepage = "https://data-apis.org/"
+
+[project.optional-dependencies]
+doc = [
+    "sphinx==4.3.0",
+    "sphinx-material==0.0.30",
+    "myst-parser",
+    "sphinx_markdown_tables",
+    "sphinx_copybutton",
+    "docutils<0.18",
+    "sphinx-math-dollar",
+]
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"