This repository contains documents, tooling and other content related to the API standard for arrays (or tensors).
These are relevant documents related to the content in this repository:
- Rendered html docs for latest version
- Consortium announcement blog post
- Blog post on first release of draft array API standard
See CONTRIBUTING.md for how to go about contributing to this array API standard.
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.
$ pip install -r doc-requirements.txt
$ make
$ ls _site/
2021.12/ draft/ index.html latest/ versions.jsonThe 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.
$ sphinx-build spec/2012.12/ _site/2012.12/Additionally, make draft aliases
$ sphinx-build spec/draft/ _site/draft/To build the whole website, which includes every version of the spec, you can
utilize make spec.
The Sphinx doc at spec/draft/ should be where the in-development spec resides,
with src/array_api_stubs/_draft/ containing its respective stubs. A spec
release should involve:
-
Renaming
src/array_api_stubs/_draft/tosrc/array_api_stubs/_YYYY_MM -
Renaming
spec/draft/tospec/YYYY.MM -
Updating
spec/YYYY.MM/conf.py... - from array_api_stubs import _draft as stubs_mod + from array_api_stubs import _YYYY_MM as stubs_mod ... - release = "DRAFT" + release = "YYYY.MM" ...
-
Updating
spec/_ghpages/versions.json{ + "YYYY.MM": "YYYY.MM", ... -
Updating
Makefile... -sphinx-build "$(SOURCEDIR)/PREVIOUS.VER" "$(BUILDDIR)/PREVIOUS.VER" $(SPHINXOPTS) + -sphinx-build "$(SOURCEDIR)/YYYY.MM" "$(BUILDDIR)/YYYY.MM" $(SPHINXOPTS) - -cp -r "$(BUILDDIR)/PREVIOUS.VER" "$(BUILDDIR)/latest" + -cp -r "$(BUILDDIR)/YYYY.MM" "$(BUILDDIR)/latest" ...
These changes should be committed and tagged. The next draft should then be created. To preserve git history for both the new release and the next draft:
- Create and checkout to a new temporary branch.
$ git checkout -b tmp- Make an empty commit. This is required so merging the temporary branch (4.) is not automatic.
$ git commit --allow-empty -m "Empty commit for draft at YYYY.MM "- Checkout back to the branch you are making a spec release in.
$ git checkout YYYY.MM-release- Merge the temporary branch, specifying no commit and no fast-forwarding.
$ git merge --no-commit --no-ff tmp
Automatic merge went well; stopped before committing as requested- Checkout the
spec/draft/files from the temporary branch.
$ git checkout tmp -- spec/draft/- Commit your changes.
$ git commit -m "Copy YYYY.MM as draft with preserved git history"You can run git blame on both spec/YYYY.MM and spec/draft files to verify
we've preserved history. See this StackOverflow question
for more background on the approach we use.
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!