Skip to content

Commit f56de3c

Browse files
honnohonno
committed
Squashed previous all-versions work
* Rudimentary `array_api_stubs` pkg and folder-per-version docs * Regex nitpick ignore for array types * Move `2021.12` docs to respective sub-folders * Fix autosummary by patching stub sub-modules in `conf.py` * Rudimentary build-all Makefile rule * Specify versions in `conf.py` * Use `versions.json` method for sphinx-material Otherwise don't think we can get links working on nested pages Notably this usually won't work locally - see https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors/CORSRequestNotHttp * Update image paths to shared `_static/` * Use vars in `make build` definition * Expand regex used to identify unwanted type hint prefixes * Update `pages.yml` workflow * Store gh-pages `.gitignore` in `main` to be copied over * `_spec_conf.py` -> `_array_api_conf.py` * Basic package necessities * Replace `requirements.txt` with extra dependency `doc` * Basic local build guide * Update preview workflow * Remove out-of-date make things, new top-level Makefile * Minor `CONTRIBUTING.md` improvements * Basic `_array_api_conf.py` module docstring * Move quickstart to `README.md` * Use `array_api` as opposed to `signatures` for `2021.12` autodoc * More consistent Makefile * Introduce `_ghpages` to hold the non-Sphinx static files * Rudimentary spec release guide * Guide to preserve history for future spec releases
1 parent 0683c70 commit f56de3c

File tree

18 files changed

+466
-87
lines changed

18 files changed

+466
-87
lines changed

‎.circleci/config.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,10 +19,10 @@ jobs:
1919
name: build docs
2020
no_output_timeout: 25m
2121
command: |
22-
pip install -r requirements.txt
23-
sphinx-build -b html -WT --keep-going spec build/draft -d doctrees
22+
pip install .[doc]
23+
make
2424
- store_artifacts:
25-
path: build/draft
25+
path: _site/
2626

2727
workflows:
2828
version: 2

‎.github/workflows/pages.yml‎

Lines changed: 6 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -76,22 +76,14 @@ jobs:
7676
# Install dependencies:
7777
- name: 'Install dependencies'
7878
run: |
79-
pip install -r ./requirements.txt
79+
pip install .[doc]
8080
8181
# Generate the documentation:
8282
- name: 'Build documentation'
8383
run: |
8484
# Turn warnings into errors and ensure .doctrees is not deployed:
85-
sphinx-build -b html -WT --keep-going spec build/draft -d doctrees
86-
87-
# Upload the build artifact:
88-
- name: 'Upload build artifact'
89-
uses: actions/upload-artifact@v2
90-
if: ${{ github.event_name == 'pull_request'}}
91-
with:
92-
name: html
93-
path: build/
94-
if-no-files-found: error
85+
export SPHINXOPTS="-b html -WT --keep-going -d doctrees"
86+
make
9587
9688
# Configure Git:
9789
- name: 'Configure Git'
@@ -107,10 +99,10 @@ jobs:
10799
git checkout gh-pages
108100
timeout-minutes: 5
109101

110-
# Copy build artifact:
111-
- name: 'Copy build artifact'
102+
- name: 'Copy build to root'
112103
run: |
113-
rm -rf ./draft && cp -R ./build/draft ./draft
104+
cp -R ./_site/* .
105+
cp ./_site/.gitignore .
114106
timeout-minutes: 10
115107

116108
# Commit changes to:

‎.github/workflows/preview.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,6 @@ jobs:
1111
uses: larsoner/circleci-artifacts-redirector-action@master
1212
with:
1313
repo-token: ${{ secrets.GITHUB_TOKEN }}
14-
artifact-path: 0/build/draft/index.html
14+
artifact-path: 0/_site/draft/index.html
1515
circleci-jobs: build_page
1616
job-title: Check the rendered docs here!

‎.gitignore‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,12 +22,15 @@
2222
# SOFTWARE.
2323
#/
2424

25-
spec/_build/
25+
_site/
2626
doctrees/
2727
build/
2828
.vscode/
2929
node_modules/
3030
__pycache__/
3131
*.pyc
3232
spec/**/generated
33-
tmp/
33+
tmp/
34+
*.egg-info/
35+
*.egg
36+
dist/

‎MANIFEST.in‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
exclude README.md
2+
exclude src/_array_api_conf.py
3+
include PACKAGE.md

‎Makefile‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# You can set these variables from the command line.
2+
SPHINXOPTS ?= -W --keep-going
3+
SOURCEDIR = spec
4+
BUILDDIR = _site
5+
6+
.PHONY: default clean build
7+
8+
default: clean build
9+
10+
clean:
11+
-rm -rf $(BUILDDIR)
12+
-find . -type d -name generated -exec rm -rf {} +
13+
14+
build:
15+
-mkdir -p $(BUILDDIR)
16+
-cp "$(SOURCEDIR)/_ghpages/_gitignore.txt" "$(BUILDDIR)/.gitignore"
17+
-cp "$(SOURCEDIR)/_ghpages/versions.json" "$(BUILDDIR)/versions.json"
18+
-cp "$(SOURCEDIR)/_ghpages/index.html" "$(BUILDDIR)/index.html"
19+
-touch "$(BUILDDIR)/.nojekyll"
20+
-sphinx-build "$(SOURCEDIR)/2021.12" "$(BUILDDIR)/2021.12" $(SPHINXOPTS)
21+
-cp -r "$(BUILDDIR)/2021.12" "$(BUILDDIR)/latest"
22+
-sphinx-build "$(SOURCEDIR)/draft" "$(BUILDDIR)/draft" $(SPHINXOPTS)

‎PACKAGE.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Stubs for the array API standard
2+
3+
Documentation specific to singular Python objects in the spec (i.e. functions,
4+
methods and attributes) are infact represented by stub objects in the package
5+
`array-api-stubs`. These stubs ultimately get rendered via the autodoc
6+
capabilities in Sphinx.
7+
8+
TODO: describe how `array-api-stubs` can be used for tooling, once it actually
9+
has the capacity to do so.

‎README.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,122 @@ These are relevant documents related to the content in this repository:
1515
See [CONTRIBUTING.md](CONTRIBUTING.md) for how to go about contributing to
1616
this array API standard.
1717

18+
19+
## Building docs locally
20+
21+
The spec website comprises of multiple Sphinx docs (one for each spec version),
22+
all of which exist in `spec/` and rely on the modules found in `src/` (most
23+
notably `array_api_stubs`). To install these modules and the additional
24+
dependencies of the Sphinx docs, you can use
25+
26+
```sh
27+
$ pip install -e .[doc] # ensure you install the dependencies extra "doc"
28+
```
29+
30+
To build specific versions of the spec, run `sphinx-build` on the respective
31+
folder in `spec/`, e.g.
32+
33+
```sh
34+
$ sphinx-build spec/draft/ _site/draft/
35+
```
36+
37+
To build the whole website, which includes every version of
38+
the spec, you can utilize the `make` commands defined in `spec/Makefile`, e.g.
39+
40+
```sh
41+
$ make
42+
$ ls _site/
43+
2021.12/ draft/ index.html latest/ versions.json
44+
```
45+
46+
47+
## Making a spec release
48+
49+
The Sphinx doc at `spec/draft/` should be where the in-development spec resides,
50+
with `src/array_api_stubs/_draft/` containing its respective stubs. A spec
51+
release should involve:
52+
53+
* Renaming `src/array_api_stubs/_draft/` to `src/array_api_stubs/_YYYY_MM`
54+
* Renaming `spec/draft/` to `spec/YYYY.MM`
55+
* Updating `spec/YYYY.MM/conf.py`
56+
57+
```diff
58+
...
59+
- from array_api_stubs import _draft as stubs_mod
60+
+ from array_api_stubs import _YYYY_MM as stubs_mod
61+
...
62+
- release = "DRAFT"
63+
+ release = "YYYY.MM"
64+
...
65+
```
66+
67+
* Updating `spec/_ghpages/versions.json`
68+
69+
```diff
70+
{
71+
+ "YYYY.MM": "YYYY.MM",
72+
...
73+
```
74+
75+
* Updating `Makefile`
76+
77+
```diff
78+
...
79+
-sphinx-build "$(SOURCEDIR)/PREVIOUS.VER" "$(BUILDDIR)/PREVIOUS.VER" $(SPHINXOPTS)
80+
+ -sphinx-build "$(SOURCEDIR)/YYYY.MM" "$(BUILDDIR)/YYYY.MM" $(SPHINXOPTS)
81+
- -cp -r "$(BUILDDIR)/PREVIOUS.VER" "$(BUILDDIR)/latest"
82+
+ -cp -r "$(BUILDDIR)/YYYY.MM" "$(BUILDDIR)/latest"
83+
...
84+
```
85+
86+
These changes should be committed and tagged. The next draft should then be
87+
created. To preserve git history for both the new release and the next draft:
88+
89+
1. Create and checkout to a new temporary branch.
90+
91+
```sh
92+
$ git checkout -b tmp
93+
```
94+
95+
2. Make an empty commit. <sup>This is required so merging the temporary branch
96+
(4.) is not automatic.</sup>
97+
98+
```sh
99+
$ git commit --allow-empty -m "Empty commit for draft at YYYY.MM "
100+
```
101+
102+
3. Checkout back to the branch you are making a spec release in.
103+
104+
```sh
105+
$ git checkout YYYY.MM-release
106+
```
107+
108+
4. Merge the temporary branch, specifying no commit and no fast-forwarding.
109+
110+
```sh
111+
$ git merge --no-commit --no-ff tmp
112+
Automatic merge went well; stopped before committing as requested
113+
```
114+
115+
5. Checkout the `spec/draft/` files from the temporary branch.
116+
117+
```sh
118+
$ git checkout tmp -- spec/draft/
119+
```
120+
121+
6. Commit your changes.
122+
123+
```sh
124+
$ git commit -m "Copy YYYY.MM as draft with preserved git history"
125+
```
126+
127+
You can run `git blame` on both `spec/YYYY.MM` and `spec/draft` files to verify
128+
we've preserved history. See this [StackOverflow question](https://stackoverflow.com/q/74365771/5193926)
129+
for more background on the approach we use.
130+
131+
<!-- TODO: write a script to automate/standardise spec releases -->
132+
133+
18134
## Contributors ✨
19135

20136
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

‎pyproject.toml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
[project]
2+
name = "array-api-stubs"
3+
version = "0.0.2"
4+
description = "Stubs for the array API standard"
5+
authors = []
6+
license = {file = "LICENSE"}
7+
readme = "PACKAGE.md"
8+
requires-python = ">=3.8"
9+
keywords = []
10+
classifiers = []
11+
12+
[project.urls]
13+
Source = "https://github.com/data-apis/array-api/"
14+
Documentation = "https://data-apis.org/array-api/"
15+
Homepage = "https://data-apis.org/"
16+
17+
[project.optional-dependencies]
18+
doc = [
19+
"sphinx==4.3.0",
20+
"sphinx-material==0.0.30",
21+
"myst-parser",
22+
"sphinx_markdown_tables",
23+
"sphinx_copybutton",
24+
"docutils<0.18",
25+
"sphinx-math-dollar",
26+
]
27+
28+
[build-system]
29+
requires = ["setuptools"]
30+
build-backend = "setuptools.build_meta"

‎requirements.txt‎

Lines changed: 0 additions & 7 deletions
This file was deleted.

0 commit comments

Comments
 (0)