Improvments to doc building with make (#587)

Author: honno

.circleci/config.yml

@@ -19,8 +19,8 @@ jobs:
           name: build docs
           no_output_timeout: 25m
           command: |
-            pip install .[doc]
-            make
+            pip install -r doc-requirements.txt
+            make spec
       - store_artifacts:
           path: _site/
 

.github/workflows/pages.yml

@@ -76,14 +76,14 @@ jobs:
       # Install dependencies:
       - name: 'Install dependencies'
         run: |
-          pip install .[doc]
+          pip install -r doc-requirements.txt
 
       # Generate the documentation:
       - name: 'Build documentation'
         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,19 @@ SPHINXOPTS    ?= -W --keep-going
 SOURCEDIR     = spec
 BUILDDIR      = _site
 
-.PHONY: default clean build
+.PHONY: default clean draft spec
 
-default: clean build
+default: clean spec
 
 clean:
-	-rm -rf $(BUILDDIR)
-	-find . -type d -name generated -exec rm -rf {} +
+	rm -rf $(BUILDDIR)
+	find . -type d -name generated -exec rm -rf {} +
 
-build:
+draft:
+	mkdir -p $(BUILDDIR)
+	sphinx-build "$(SOURCEDIR)/draft" "$(BUILDDIR)/draft" $(SPHINXOPTS)
+
+spec:
 	mkdir -p $(BUILDDIR)
 	cp "$(SOURCEDIR)/_ghpages/_gitignore.txt" "$(BUILDDIR)/.gitignore"
 	cp "$(SOURCEDIR)/_ghpages/versions.json" "$(BUILDDIR)/versions.json"

README.md

@@ -18,31 +18,43 @@ 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
+### Quickstart
+
+To install the local stubs and additional dependencies of the Sphinx docs, you
+can use `pip install -r doc-requirements.txt`. Then just running `make` at the
+root of the repository should build the whole spec website.
 
 ```sh
-$ pip install -e .[doc]  # ensure you install the dependencies extra "doc"
+$ pip install -r doc-requirements.txt
+$ 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`). For purposes of building the docs, these `src/`
+modules do not need to be installed as they are added to the `sys.path` at
+runtime.
+
 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
 

doc-requirements.txt

@@ -0,0 +1,7 @@
+sphinx==4.3.0
+sphinx-material==0.0.30
+myst-parser
+sphinx_markdown_tables
+sphinx_copybutton
+docutils<0.18
+sphinx-math-dollar

pyproject.toml

@@ -14,17 +14,6 @@ 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"

spec/2021.12/conf.py

@@ -1,4 +1,6 @@
 import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parents[2] / "src"))
 
 from array_api_stubs import _2021_12 as stubs_mod
 from _array_api_conf import *

spec/2022.12/conf.py

@@ -1,4 +1,6 @@
 import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parents[2] / "src"))
 
 from array_api_stubs import _2022_12 as stubs_mod
 from _array_api_conf import *

spec/draft/conf.py

@@ -1,4 +1,6 @@
 import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parents[2] / "src"))
 
 from array_api_stubs import _draft as stubs_mod
 from _array_api_conf import *