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

honno · honno · commit 6532d5b89feb · 2023-02-23T11:56:06.000Z
i.e. so you don't have to explicitly install things to build docs
diff --git a/Makefile b/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 {} +
diff --git a/README.md b/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.
diff --git a/doc-requirements.txt b/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
diff --git a/pyproject.toml b/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"
diff --git a/spec/2021.12/conf.py b/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 *
diff --git a/spec/2022.12/conf.py b/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 *
diff --git a/spec/draft/conf.py b/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 *
