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 * 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