From e1a29a1a8490b4bbd4ccc67740bc61ff8b92253a Mon Sep 17 00:00:00 2001 From: Matthew Barber Date: Wed, 1 Feb 2023 10:05:28 +0000 Subject: [PATCH 1/3] Improved `make` command --- .circleci/config.yml | 2 +- .github/workflows/pages.yml | 2 +- Makefile | 17 ++++++++++++----- README.md | 27 ++++++++++++++++++++------- 4 files changed, 34 insertions(+), 14 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index cecae43c8..15e964727 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -20,7 +20,7 @@ jobs: no_output_timeout: 25m command: | pip install .[doc] - make + make spec - store_artifacts: path: _site/ diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index e615135d3..035ff4ede 100644 --- a/.github/workflows/pages.yml +++ b/.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' diff --git a/Makefile b/Makefile index a48139ddc..537d0d437 100644 --- a/Makefile +++ b/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" diff --git a/README.md b/README.md index 529afdbb9..2970f246a 100644 --- a/README.md +++ b/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 From cf56f4677b760fa82328b676ca1662d1217ede55 Mon Sep 17 00:00:00 2001 From: Matthew Barber Date: Thu, 2 Feb 2023 09:31:31 +0000 Subject: [PATCH 2/3] Seperate `make install` from `make` --- Makefile | 2 +- README.md | 9 +++++---- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/Makefile b/Makefile index 537d0d437..1cbeb7fc0 100644 --- a/Makefile +++ b/Makefile @@ -5,7 +5,7 @@ BUILDDIR = _site .PHONY: default install clean draft spec -default: install clean spec +default: clean spec install: pip install -e .[doc] diff --git a/README.md b/README.md index 2970f246a..77513de03 100644 --- a/README.md +++ b/README.md @@ -20,10 +20,12 @@ this array API standard. ### Quickstart -Just running `make` at the root of the repository should install the necessary -dependencies and build the whole spec website. +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. ```sh +$ make install $ make $ ls _site/ 2021.12/ draft/ index.html latest/ versions.json @@ -33,8 +35,7 @@ $ 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`). To install these modules and the additional -dependencies of the Sphinx docs, you can use `make install`, which aliases +notably `array_api_stubs`). `make install` aliases ```sh $ pip install -e .[doc] # ensure you install the dependencies extra "doc" From 19ad87cb04d879e55aa37fa8542f8b8f170e1ee3 Mon Sep 17 00:00:00 2001 From: Matthew Barber Date: Thu, 23 Feb 2023 11:56:06 +0000 Subject: [PATCH 3/3] `sys.path.insert()` the `src/` path per `conf.py` i.e. so you don't have to explicitly install things to build docs --- .circleci/config.yml | 2 +- .github/workflows/pages.yml | 2 +- Makefile | 5 +---- README.md | 14 ++++++-------- doc-requirements.txt | 7 +++++++ pyproject.toml | 11 ----------- spec/2021.12/conf.py | 2 ++ spec/2022.12/conf.py | 2 ++ spec/draft/conf.py | 2 ++ 9 files changed, 22 insertions(+), 25 deletions(-) create mode 100644 doc-requirements.txt diff --git a/.circleci/config.yml b/.circleci/config.yml index 15e964727..b35ab8506 100644 --- a/.circleci/config.yml +++ b/.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/ diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 035ff4ede..b328abc11 100644 --- a/.github/workflows/pages.yml +++ b/.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' diff --git a/Makefile b/Makefile index 1cbeb7fc0..d23e05218 100644 --- 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 index 77513de03..6c32aec19 100644 --- 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 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 *