Merge pull request #28 from asmeurer/docs

Add basic documentation, based on the README

Author: asmeurer

.github/workflows/docs-build.yml

@@ -0,0 +1,22 @@
+name: Docs Build
+
+on: [push, pull_request]
+
+jobs:
+  docs-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+      - name: Install Dependencies
+        run: |
+          python -m pip install -r docs/requirements.txt
+      - name: Build Docs
+        run: |
+          cd docs
+          make html
+      - name: Upload Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-build
+          path: docs/_build/html

.github/workflows/docs-deploy.yml

@@ -0,0 +1,30 @@
+name: Docs Deploy
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  docs-deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: docs-deploy
+    steps:
+      - uses: actions/checkout@v4
+      - name: Download Artifact
+        uses: dawidd6/action-download-artifact@v2
+        with:
+          workflow: docs-build.yml
+          name: docs-build
+          path: docs/_build/html
+
+      # Note, the gh-pages deployment requires setting up a SSH deploy key.
+      # See
+      # https://github.com/JamesIves/github-pages-deploy-action/tree/dev#using-an-ssh-deploy-key-
+      - name: Deploy
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          folder: docs/_build/html
+          ssh-key: ${{ secrets.DEPLOY_KEY }}
+          force: no

CHANGELOG.md

@@ -0,0 +1 @@
+docs/changelog.md

CHANGELOG.md

@@ -1,7 +1,7 @@
 # array-api-strict
 
 `array_api_strict` is a strict, minimal implementation of the [Python array
-API](https://data-apis.org/array-api/latest/)
+API](https://data-apis.org/array-api/latest/).
 
 The purpose of array-api-strict is to provide an implementation of the array
 API for consuming libraries to test against so they can be completely sure
@@ -11,191 +11,12 @@ It is *not* intended to be used by end-users. End-users of the array API
 should just use their favorite array library (NumPy, CuPy, PyTorch, etc.) as
 usual. It is also not intended to be used as a dependency by consuming
 libraries. Consuming library code should use the
-[array-api-compat](https://github.com/data-apis/array-api-compat) package to
+[array-api-compat](https://data-apis.org/array-api-compat/) package to
 support the array API. Rather, it is intended to be used in the test suites of
 consuming libraries to test their array API usage.
 
 array-api-strict currently supports the 2022.12 version of the standard.
 2023.12 support is planned and is tracked by [this
 issue](https://github.com/data-apis/array-api-strict/issues/25).
 
-## Install
-
-`array-api-strict` is available on both
-[PyPI](https://pypi.org/project/array-api-strict/)
-
-```
-python -m pip install array-api-strict
-```
-
-and [Conda-forge](https://anaconda.org/conda-forge/array-api-strict)
-
-```
-conda install --channel conda-forge array-api-strict
-```
-
-array-api-strict supports NumPy 1.26 and (the upcoming) NumPy 2.0.
-
-## Rationale
-
-The array API has many functions and behaviors that are required to be
-implemented by conforming libraries, but it does not, in most cases, disallow
-implementing additional functions, keyword arguments, and behaviors that
-aren't explicitly required by the standard.
-
-However, this poses a problem for consumers of the array API, as they may
-accidentally use a function or rely on a behavior which just happens to be
-implemented in every array library they test against (e.g., NumPy and
-PyTorch), but isn't required by the standard and may not be included in other
-libraries.
-
-array-api-strict solves this problem by providing a strict, minimal
-implementation of the array API standard. Only those functions and behaviors
-that are explicitly *required* by the standard are implemented. For example,
-most NumPy functions accept Python scalars as inputs:
-
-```py
->>> import numpy as np
->>> np.sin(0.0)
-0.0
-```
-
-However, the standard only specifies function inputs on `Array` objects. And
-indeed, some libraries, such as PyTorch, do not allow this:
-
-```py
->>> import torch
->>> torch.sin(0.0)
-Traceback (most recent call last):
-  File "<stdin>", line 1, in <module>
-TypeError: sin(): argument 'input' (position 1) must be Tensor, not float
-```
-
-In array-api-strict, this is also an error:
-
-```py
->>> import array_api_strict as xp
->>> xp.sin(0.0)
-Traceback (most recent call last):
-...
-AttributeError: 'float' object has no attribute 'dtype'
-```
-
-Here is an (incomplete) list of the sorts of ways that array-api-strict is
-strict/minimal:
-
-- Only those functions and methods that are [defined in the
-  standard](https://data-apis.org/array-api/latest/API_specification/index.html)
-  are included.
-
-- In those functions, only the keyword-arguments that are defined by the
-  standard are included. All signatures in array-api-strict use
-  [positional-only
-  arguments](https://data-apis.org/array-api/latest/API_specification/function_and_method_signatures.html#function-and-method-signatures).
-  As noted above, only `array_api_strict` array objects are accepted by
-  functions, except in the places where the standard allows Python scalars
-  (i.e., functions do not automatically call `asarray` on their inputs).
-
-- Only those [dtypes that are defined in the
-  standard](https://data-apis.org/array-api/latest/API_specification/data_types.html)
-  are included.
-
-- All functions and methods reject inputs if the standard does not *require*
-  the input dtype(s) to be supported. This is one of the most restrictive
-  aspects of the library. For example, in NumPy, most transcendental functions
-  like `sin` will accept integer array inputs, but the [standard only requires
-  them to accept floating-point
-  inputs](https://data-apis.org/array-api/latest/API_specification/generated/array_api.sin.html#array_api.sin),
-  so in array-api-strict, `sin(integer_array)` will raise an exception.
-
-- The
-  [indexing](https://data-apis.org/array-api/latest/API_specification/indexing.html)
-  semantics required by the standard are limited compared to those implemented
-  by NumPy (e.g., out-of-bounds slices are not supported, integer array
-  indexing is not supported, only a single boolean array index is supported).
-
-- There are no distinct "scalar" objects as in NumPy. There are only 0-D
-  arrays.
-
-- Dtype objects are just empty objects that only implement [equality
-  comparison](https://data-apis.org/array-api/latest/API_specification/generated/array_api.data_types.__eq__.html).
-  The way to access dtype objects in the standard is by name, like
-  `xp.float32`.
-
-- The array object type itself is private and should not be accessed.
-  Subclassing or otherwise trying to directly initialize this object is not
-  supported. Arrays should be created with one of the [array creation
-  functions](https://data-apis.org/array-api/latest/API_specification/creation_functions.html)
-  such as `asarray`.
-
-## Caveats
-
-array-api-strict is a thin pure Python wrapper around NumPy. NumPy 2.0 fully
-supports the array API but NumPy 1.26 does not, so many behaviors are wrapped
-in NumPy 1.26 to provide array API compatible behavior. Although it is based
-on NumPy, mixing NumPy arrays with array-api-strict arrays is not supported.
-This should generally raise an error, as it indicates a potential portability
-issue, but this hasn't necessarily been tested thoroughly.
-
-1. array-api-strict is validated against the [array API test
-   suite](https://github.com/data-apis/array-api-tests). However, there may be
-   a few minor instances where NumPy deviates from the standard in a way that
-   is inconvenient to workaround in array-api-strict, since it aims to remain
-   pure Python. You can see the full list of tests that are known to fail in
-   the [xfails
-   file](https://github.com/data-apis/array-api-strict/blob/main/array-api-tests-xfails.txt).
-
-    The most notable of these is that in NumPy 1.26, the `copy=False` flag is
-    not implemented for `asarray` and therefore `array_api_strict` raises
-    `NotImplementedError` in that case.
-
-2. Since NumPy is a CPU-only library, the [device
-   support](https://data-apis.org/array-api/latest/design_topics/device_support.html)
-   in array-api-strict is superficial only. `x.device` is always a (private)
-   `CPU_DEVICE` object, and `device` keywords to creation functions only
-   accept either this object or `None`. A future version of array-api-strict
-   [may add support for a CuPy
-   backend](https://github.com/data-apis/array-api-strict/issues/5) so that
-   more significant device support can be tested.
-
-3. Although only array types are expected in array-api-strict functions,
-   currently most functions do not do extensive type checking on their inputs,
-   so a sufficiently duck-typed object may pass through silently (or at best,
-   you may get `AttributeError` instead of `TypeError`). However, all type
-   signatures have type annotations (based on those from the standard), so
-   this deviation may be tested with type checking. This [behavior may improve
-   in the future](https://github.com/data-apis/array-api-strict/issues/6).
-
-4. There are some behaviors in the standard that are not required to be
-   implemented by libraries that cannot support [data dependent
-   shapes](https://data-apis.org/array-api/latest/design_topics/data_dependent_output_shapes.html).
-   This includes [the `unique_*`
-   functions](https://data-apis.org/array-api/latest/API_specification/set_functions.html),
-   [boolean array
-   indexing](https://data-apis.org/array-api/latest/API_specification/indexing.html#boolean-array-indexing),
-   and the
-   [`nonzero`](https://data-apis.org/array-api/latest/API_specification/generated/array_api.nonzero.html)
-   function. array-api-strict currently implements all of these. In the
-   future, [there may be a way to disable them](https://github.com/data-apis/array-api-strict/issues/7).
-
-5. array-api-strict currently only supports the latest version of the array
-   API standard. [This may change in the future depending on
-   need](https://github.com/data-apis/array-api-strict/issues/8).
-
-## Usage
-
-TODO: Add a sample CI script here.
-
-## Relationship to `numpy.array_api`
-
-Previously this implementation was available as `numpy.array_api`, but it was
-moved to a separate package for NumPy 2.0.
-
-Note that the history of this repo prior to commit
-fbefd42e4d11e9be20e0a4785f2619fc1aef1e7c was generated automatically
-from the numpy git history, using the following
-[git-filter-repo](https://github.com/newren/git-filter-repo) command:
-
-```
-git_filter_repo.py --path numpy/array_api/ --path-rename numpy/array_api:array_api_strict --replace-text <(echo -e "numpy.array_api==>array_api_strict\nfrom ..core==>from numpy.core\nfrom .._core==>from numpy._core\nfrom ..linalg==>from numpy.linalg\nfrom numpy import array_api==>import array_api_strict") --commit-callback 'commit.message = commit.message.rstrip() + b"\n\nOriginal NumPy Commit: " + commit.original_id'
-```
+See the documentation for more details https://data-apis.org/array-api-strict/

README.md

@@ -10,7 +10,7 @@
 should just use their favorite array library (NumPy, CuPy, PyTorch, etc.) as
 usual. It is also not intended to be used as a dependency by consuming
 libraries. Consuming library code should use the
-array-api-compat (https://github.com/data-apis/array-api-compat) package to
+array-api-compat (https://data-apis.org/array-api-compat/) package to
 support the array API. Rather, it is intended to be used in the test suites of
 consuming libraries to test their array API usage.
 

array_api_strict/__init__.py

@@ -0,0 +1,23 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+livehtml:
+	sphinx-autobuild --open-browser --watch .. --port 0 -b html $(SOURCEDIR) $(ALLSPHINXOPTS) $(BUILDDIR)/html

docs/Makefile

@@ -0,0 +1,12 @@
+/* Makes the text look better on Mac retina displays (the Furo CSS disables*/
+/* subpixel antialiasing). */
+body {
+    -webkit-font-smoothing: auto;
+    -moz-osx-font-smoothing: auto;
+}
+
+/* Disable the fancy scrolling behavior when jumping to headers (this is too
+   slow for long pages) */
+html {
+    scroll-behavior: auto;
+}

docs/_static/custom.css

@@ -0,0 +1,45 @@
+# Changelog
+
+## 1.1.1 (2024-04-29)
+
+- Fix the `api_version` argument to `__array_namespace__` to accept
+  `'2021.12'` or `'2022.12'`.
+
+## 1.1 (2024-04-08)
+
+- Fix the `copy` flag in `__array__` for NumPy 2.0.
+
+- Add full `copy=False` support to `asarray()`. This is emulated in NumPy 1.26 by creating
+  the array and seeing if it is copied. For NumPy 2.0, the new native
+  `copy=False` flag is used.
+
+- Add broadcasting support to `cross`.
+
+## 1.0 (2024-01-24)
+
+This is the first release of `array_api_strict`. It is extracted from
+`numpy.array_api`, which was included as an experimental submodule in NumPy
+versions prior to 2.0. Note that the commit history in this repository is
+extracted from the git history of numpy/array_api/ (see the [README](README.md)).
+
+Additionally, the following changes are new to `array_api_strict` from
+`numpy.array_api` in NumPy 1.26 (the last NumPy feature release to include
+`numpy.array_api`):
+
+- ``array_api_strict`` was made more portable. In particular:
+
+  - ``array_api_strict`` no longer uses ``"cpu"`` as its "device", but rather a
+    separate ``CPU_DEVICE`` object (which is not accessible in the namespace).
+    This is because "cpu" is not part of the array API standard.
+
+  - ``array_api_strict`` now uses separate wrapped objects for dtypes.
+    Previously it reused the ``numpy`` dtype objects. This makes it clear
+    which behaviors on dtypes are part of the array API standard (effectively,
+    the standard only requires ``==`` on dtype objects).
+
+- ``numpy.array_api.nonzero`` now errors on zero-dimensional arrays, as
+    required by the array API standard.
+
+- Support for the optional [fft
+  extension](https://data-apis.org/array-api/latest/extensions/fourier_transform_functions.html)
+  was added.