sys.path.insert() the src/ path per conf.py

i.e. so you don't have to explicitly install things to build docs

Author: honno

.circleci/config.yml

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

.github/workflows/pages.yml

@@ -76,7 +76,7 @@ jobs:
       # Install dependencies:
       - name: 'Install dependencies'
         run: |
-          pip install .[doc]
+          pip install -r doc-requirements.txt
 
       # Generate the documentation:
       - name: 'Build documentation'

Makefile

@@ -3,13 +3,10 @@ SPHINXOPTS    ?= -W --keep-going
 SOURCEDIR     = spec
 BUILDDIR      = _site
 
-.PHONY: default install clean draft spec
+.PHONY: default clean draft spec
 
 default: clean spec
 
-install:
-	pip install -e .[doc]
-
 clean:
 	rm -rf $(BUILDDIR)
 	find . -type d -name generated -exec rm -rf {} +

README.md

@@ -21,11 +21,11 @@ this array API standard.
 ### Quickstart
 
 To install the local stubs and additional dependencies of the Sphinx docs, you
-can use `make install`. Then just running `make` at the root of the repository
-should build the whole spec website.
+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
-$ make install
+$ pip install -r doc-requirements.txt
 $ make
 $ ls _site/
 2021.12/  draft/  index.html  latest/  versions.json
@@ -35,11 +35,9 @@ $ ls _site/
 
 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`). `make install` aliases
-
-```sh
-$ pip install -e .[doc]  # ensure you install the dependencies extra "doc"
-```
+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.

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 *