diff --git a/.circleci/config.yml b/.circleci/config.yml
index cecae43c8..b35ab8506 100644
--- a/.circleci/config.yml
+++ b/.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/
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
index e615135d3..b328abc11 100644
--- a/.github/workflows/pages.yml
+++ b/.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'
diff --git a/Makefile b/Makefile
index a48139ddc..d23e05218 100644
--- a/Makefile
+++ b/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"
diff --git a/README.md b/README.md
index 529afdbb9..6c32aec19 100644
--- a/README.md
+++ b/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
diff --git a/doc-requirements.txt b/doc-requirements.txt
new file mode 100644
index 000000000..230413784
--- /dev/null
+++ 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
index b8240a665..f39bf48b9 100644
--- 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
index d9ec5b030..04af8974d 100644
--- 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
index e9d652d44..fd05b644e 100644
--- 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
index f3804e7ad..4a57229b2 100644
--- 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 *
pFad - Phonifier reborn
Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.
Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.
Alternative Proxies:
Alternative Proxy
pFad Proxy
pFad v3 Proxy
pFad v4 Proxy