make improvments

.circleci/config.yml

@@ -20,7 +20,7 @@ jobs:
           no_output_timeout: 25m
           command: |
             pip install .[doc]
-            make
+            make spec
       - store_artifacts:
           path: _site/
 

.github/workflows/pages.yml

@@ -83,7 +83,7 @@ jobs:
         run: |
           # Turn warnings into errors and ensure .doctrees is not deployed:
           export SPHINXOPTS="-b html -WT --keep-going -d doctrees"
-          make
+          make spec
 
       # Configure Git:
       - name: 'Configure Git'

Makefile

@@ -3,15 +3,22 @@ SPHINXOPTS    ?= -W --keep-going
 SOURCEDIR     = spec
 BUILDDIR      = _site
 
-.PHONY: default clean build
+.PHONY: default install clean draft spec
 
-default: clean build
+default: install clean spec
+
+install:
+	pip install -e .[doc]
 
 clean:
-	-rm -rf $(BUILDDIR)
-	-find . -type d -name generated -exec rm -rf {} +
+	rm -rf $(BUILDDIR)
+	find . -type d -name generated -exec rm -rf {} +
+
+draft:
+	mkdir -p $(BUILDDIR)
+	sphinx-build "$(SOURCEDIR)/draft" "$(BUILDDIR)/draft" $(SPHINXOPTS)
 
-build:
+spec:
 	mkdir -p $(BUILDDIR)
 	cp "$(SOURCEDIR)/_ghpages/_gitignore.txt" "$(BUILDDIR)/.gitignore"
 	cp "$(SOURCEDIR)/_ghpages/versions.json" "$(BUILDDIR)/versions.json"

README.md

@@ -18,10 +18,23 @@ this array API standard.
 
 ## Building docs locally
 
+### Quickstart
+
+Just running `make` at the root of the repository should install the necessary
+dependencies and build the whole spec website.
+
+```sh
+$ make
+$ ls _site/
+2021.12/  draft/  index.html  latest/  versions.json
+```
+
+### The nitty-gritty
+
 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
+dependencies of the Sphinx docs, you can use `make install`, which aliases
 
 ```sh
 $ pip install -e .[doc]  # ensure you install the dependencies extra "doc"
@@ -31,18 +44,18 @@ 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/
+$ sphinx-build spec/2012.12/ _site/2012.12/
 ```
 
-To build the whole website, which includes every version of
-the spec, you can utilize the `make` commands defined in `spec/Makefile`; e.g.,
+Additionally, `make draft` aliases
 
 ```sh
-$ make
-$ ls _site/
-2021.12/  draft/  index.html  latest/  versions.json
+$ sphinx-build spec/draft/ _site/draft/
 ```
 
+To build the whole website, which includes every version of the spec, you can
+utilize `make spec`.
+
 
 ## Making a spec release