/array-api

RFC document, tooling and other content related to the array API standard

Primary LanguagePythonMIT LicenseMIT

Array API standard

All Contributors

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:

See CONTRIBUTING.md for how to go about contributing to this array API standard.

Building docs locally

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.

$ 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.

$ 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.

Making a spec release

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/ to src/array_api_stubs/_YYYY_MM

  • Renaming spec/draft/ to spec/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:

  1. Create and checkout to a new temporary branch.
$ git checkout -b tmp
  1. 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 "
  1. Checkout back to the branch you are making a spec release in.
$ git checkout YYYY.MM-release
  1. 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
  1. Checkout the spec/draft/ files from the temporary branch.
$ git checkout tmp -- spec/draft/
  1. 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.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Saul Shanabrook
Saul Shanabrook

πŸ”§ πŸ€” πŸ”¬
Athan
Athan

πŸ–‹ πŸ”£ πŸ”§ πŸ”¬
Stephannie Jimenez Gacha
Stephannie Jimenez Gacha

πŸ”£ πŸ–‹ πŸ”¬
Aaron Meurer
Aaron Meurer

πŸ–‹ ⚠️ πŸ”§
Tony Fast
Tony Fast

🚧
Ralf Gommers
Ralf Gommers

πŸ“ πŸ’Ό πŸ’» πŸ–‹ πŸ“– πŸ” 🚧 πŸ€” πŸ“† πŸ“’
Travis E. Oliphant
Travis E. Oliphant

πŸ’Ό πŸ” πŸ€”
Leo Fang
Leo Fang

πŸ‘€ πŸ€” πŸ–‹
Tianqi Chen
Tianqi Chen

πŸ€” πŸ‘€
Stephan Hoyer
Stephan Hoyer

πŸ€” πŸ‘€ πŸ’¬
Alexandre Passos
Alexandre Passos

πŸ€” πŸ‘€
Paige Bailey
Paige Bailey

πŸ”
Adam Paszke
Adam Paszke

πŸ€” πŸ‘€ πŸ“’
Andreas Mueller
Andreas Mueller

πŸ€” πŸ‘€
Sheng Zha
Sheng Zha

πŸ€”
kkraus
kkraus

πŸ€” πŸ‘€ πŸ“’
Tom Augspurger
Tom Augspurger

πŸ‘€ πŸ’¬
edloper
edloper

πŸ‘€ πŸ’¬
Areg Melik-Adamyan
Areg Melik-Adamyan

πŸ‘€ πŸ”
Oleksandr Pavlyk
Oleksandr Pavlyk

πŸ‘€ πŸ’¬
tdimitri
tdimitri

πŸ€”
Jack Pappas
Jack Pappas

πŸ€”
Ashish Agarwal
Ashish Agarwal

πŸ‘€ πŸ’¬
Edward Z. Yang
Edward Z. Yang

πŸ€”
Mike Ruberry
Mike Ruberry

πŸ€”
Eric Wieser
Eric Wieser

πŸ€”
Carol Willing
Carol Willing

πŸ€”
Alex Rogozhnikov
Alex Rogozhnikov

πŸ€”
Matthew Honnibal
Matthew Honnibal

πŸ€”
Mario Lezcano Casado
Mario Lezcano Casado

πŸ€”
Bas van Beek
Bas van Beek

πŸ€”
Sebastian Berg
Sebastian Berg

πŸ€”
Isaac Breen
Isaac Breen

πŸ€”
Kenichi Maehashi
Kenichi Maehashi

πŸ€”
Chris Pryer
Chris Pryer

πŸ€”
Tirth Patel
Tirth Patel

πŸ€”
Kshiteej K
Kshiteej K

πŸ€”
Anirudh Dagar
Anirudh Dagar

πŸ€”
Tom White
Tom White

πŸ€”
Matthew Barber
Matthew Barber

πŸ€” πŸ–‹
Philip Meier
Philip Meier

πŸ”¬ πŸ’»
Zac Hatfield-Dodds
Zac Hatfield-Dodds

πŸ€” πŸ’»
Daniel Lenton
Daniel Lenton

πŸ’»
Simone G
Simone G

πŸ’» πŸ€”
Tyler Reddy
Tyler Reddy

πŸ€”
Matt Barrett
Matt Barrett

πŸ€”
Jatin Prakash
Jatin Prakash

πŸ€”
Ishtiaq Hussain
Ishtiaq Hussain

πŸ€”
sherry30
sherry30

πŸ€”
JoΓ£o Lobo
JoΓ£o Lobo

πŸ€”
Neil Girdhar
Neil Girdhar

πŸ€”
Nathaniel Starkman
Nathaniel Starkman

πŸ€”
jakirkham
jakirkham

πŸ€”
RickSanchezStoic
RickSanchezStoic

πŸ€”
Talley Lambert
Talley Lambert

πŸ€”
Juan Nunez-Iglesias
Juan Nunez-Iglesias

πŸ€”
Christian Kothe
Christian Kothe

πŸ€”
Carlos Ramos CarreΓ±o
Carlos Ramos CarreΓ±o

πŸ€”
Gilad
Gilad

πŸ€”
Thomas J. Fan
Thomas J. Fan

πŸ€”
Conchylicultor
Conchylicultor

πŸ€”
Franck Charras
Franck Charras

πŸ€”
Keith Kraus
Keith Kraus

πŸ€”
Lucas Colley
Lucas Colley

🚧 πŸ›

This project follows the all-contributors specification. Contributions of any kind welcome!