Write some dev docs, and various other improvements to the documentation

Author: asmeurer

docs/dev/implementation-notes.md

@@ -1,5 +1,77 @@
 # Implementation Notes
 
+This page outlines some notes on the implementation of array-api-compat. These
+details are not important for users of the package, but they may be useful to
+contributors.
+
+## Special Considerations
+
+array-api-compat requires some special development considerations that are
+different from most other Python libraries. The goal of array-api-compat is to
+be a small library that packages can either vendor or add as a dependency to
+implement array API support. Consequently, certain design considerations
+should be taken into account:
+
+- *No Hard Dependencies.* Although array-api-compat "depends" on NumPy, CuPy,
+  PyTorch, etc., it does not hard depend on them. These libraries are not
+  imported unless either an array object is passed to `array_namespace()`, or
+  the specific `array_api_compat.<namespace>` sub-namespace is explicitly
+  imported.
+
+- *Vendorability.* array-api-compat should be [vendorable](vendoring). This
+  means that, for instance, all imports in the library are relative imports.
+  No code in the package specifically references the name `array_api_compat`
+  (we also support renaming the package to something else).
+  Vendorability support is tested in `tests/test_vendoring.py`.
+
+- *Pure Python.* To make array-api-compat as easy as possible to add as a
+  dependency, the code is all pure Python.
+
+- *Minimal Wrapping Only.* The wrapping functionality is minimal. This means
+  that if something is difficult to wrap using pure Python, or if trying to
+  support some array API behavior would require a significant amount of code,
+  we prefer to leave the behavior as an upstream issue for the array library,
+  and [document it as a known difference](../supported-array-libraries.md).
+
+  This also means that we do not at this point in time implement anything
+  other than wrappers for functions in the standard, and basic [helper
+  functions](../helper-functions.md) that would be useful for most users of
+  array-api-compat. The addition of functions that are not part of the array
+  API standard is currently out-of-scope for this package.
+
+- *No Monkey Patching.* `array-api-compat` should not attempt to modify anything
+  about the underlying library. It is a *wrapper* library only.
+
+- *No modifying the array object.* Due to the above restrictions, the array
+  (or tensor) object of the array library cannot be modified. Any behavior
+  that is built-in to the array object, such as the behavior of [array
+  methods](https://data-apis.org/array-api/latest/API_specification/array_object.html)
+  is therefore left unwrapped. Users can workaround issues by using
+  corresponding [elementwise
+  functions](https://data-apis.org/array-api/latest/API_specification/elementwise_functions.html)
+  instead of operators, and using the [helper
+  functions](../helper-functions.md) provided by array-api-compat instead of
+  methods like `to_device`.
+
+- *Avoid Restricting Non-Standard Behavior.* All array libraries have
+  functions and behaviors that are outside of the scope of what is specified
+  by the standard. These behaviors should be left intact whenever possible,
+  unless the standard explicitly disallows something. This means
+
+  - All namespaces are *extended* with wrapper functions. You may notice the
+    extensive use of `import *` in various files in `array_api_compat`. While
+    this would normally be questionable, this is the [one actual legitimate
+    use-case for `import *`](https://peps.python.org/pep-0008/#imports), to
+    re-export names from an external namespace.
+
+  - All wrapper functions pass `**kwargs` through to the wrapped function.
+
+  The onus is on users of array-api-compat to ensure they are only using
+  portable array API behavior, e.g., by testing against [array-api-strict](array-api-strict).
+
+
+## Avoiding Code Duplication
+
 As noted before, the goal of this library is to reuse the NumPy and CuPy array
 objects, rather than wrapping or extending them. This means that the functions
 need to accept and return `np.ndarray` for NumPy and `cp.ndarray` for CuPy.
@@ -64,3 +136,25 @@ corresponding document does not yet exist for PyTorch, but you can examine the
 various comments in the
 [implementation](https://github.com/data-apis/array-api-compat/blob/main/array_api_compat/torch/_aliases.py)
 to see what functions and behaviors have been wrapped.
+
+## Tests
+
+The majority of the behavior for array-api-compat is tested by the
+[array-api-tests](https://github.com/data-apis/array-api-tests) test suite for
+the array API standard. There are also specific tests in
+[`tests/`](https://github.com/data-apis/array-api-compat/tree/main/tests).
+These tests should be limited to things that are not tested by the test suite,
+e.g., tests for [helper functions](../helper-functions.md) or for behavior that is
+not strictly required by the standard.
+
+array-api-tests is run against all supported libraries are tested on CI
+(except for JAX,
+[wrapping](jax-support)). This is achieved by a [reusable GitHub Actions
+Workflow](https://github.com/data-apis/array-api-compat/blob/main/.github/workflows/array-api-tests.yml).
+Most libraries have tests that must be xfailed or skipped for various reasons.
+These are defined in specific `<library>-xfails.txt` files and are
+automatically forwarded to array-api-tests.
+
+Array libraries that require a GPU to run (currently only CuPy) cannot be
+tested on CI. There is a helper script `test_cupy.sh` that can be used to
+manually test CuPy on a machine with a CUDA GPU.

docs/index.md

@@ -71,14 +71,16 @@ namespace, except that functions that are part of the array API are wrapped so
 that they have the correct array API behavior. In each case, the array object
 used will be the same array object from the wrapped library.
 
+(array-api-strict)=
 ## Difference between `array_api_compat` and `array_api_strict`
 
-`array_api_strict` is a strict minimal implementation of the array API standard, formerly
-known as `numpy.array_api` (see
-[NEP 47](https://numpy.org/neps/nep-0047-array-api-standard.html)). For
-example, `array_api_strict` does not include any functions that are not part of
-the array API specification, and will explicitly disallow behaviors that are
-not required by the spec (e.g., [cross-kind type
+[`array_api_strict`](https://github.com/data-apis/array-api-strict) is a
+strict minimal implementation of the array API standard, formerly known as
+`numpy.array_api` (see [NEP
+47](https://numpy.org/neps/nep-0047-array-api-standard.html)). For example,
+`array_api_strict` does not include any functions that are not part of the
+array API specification, and will explicitly disallow behaviors that are not
+required by the spec (e.g., [cross-kind type
 promotions](https://data-apis.org/array-api/latest/API_specification/type_promotion.html)).
 (`cupy.array_api` is similar to `array_api_strict`)
 
@@ -101,6 +103,7 @@ against `array_api_strict` to ensure they are not using functionality outside
 of the standard, but prefer this implementation for the default behavior for
 end-users.
 
+(vendoring)=
 ## Vendoring
 
 This library supports vendoring as an installation method. To vendor the
@@ -122,6 +125,6 @@ Alternatively, the library may be installed as dependency on PyPI.
 :hidden:
 
 helper-functions.md
-differences.md
+supported-array-libraries.md
 dev/index.md
 ```

docs/differences.md renamed to docs/supported-array-libraries.md

@@ -1,16 +1,29 @@
-# Differences from the Array API Specification
+# Supported Array Libraries
 
-There are some known differences between this library and the array API
-specification:
+The following array libraries are supported. This page outlines the known
+differences between this library and the array API specification for the
+supported packages.
 
-## NumPy and CuPy
+Note that the [`array_namespace()`](helper-functions.md) helper will also
+support any array library that explicitly supports the array API by defining
+[`__array_namespace__`](https://data-apis.org/array-api/latest/API_specification/generated/array_api.array.__array_namespace__.html).
+
+## [NumPy](https://numpy.org/) and [CuPy](https://cupy.dev/)
+
+NumPy 2.0 has full array API compatibility. This package is not strictly
+necessary for NumPy 2.0 support, but may still be useful for the support of
+other libraries, as well as for the [helper functions](helper-functions.md).
+
+For NumPy 1.26, as well as corresponding versions of CuPy, the following
+deviations from the standard should be noted:
 
 - The array methods `__array_namespace__`, `device` (for NumPy), `to_device`,
   and `mT` are not defined. This reuses `np.ndarray` and `cp.ndarray` and we
-  don't want to monkeypatch or wrap it. The helper functions `device()` and
-  `to_device()` are provided to work around these missing methods (see above).
-  `x.mT` can be replaced with `xp.linalg.matrix_transpose(x)`.
-  `array_namespace(x)` should be used instead of `x.__array_namespace__`.
+  don't want to monkey patch or wrap it. The [helper
+  functions](helper-functions.md) `device()` and `to_device()` are provided to
+  work around these missing methods. `x.mT` can be replaced with
+  `xp.linalg.matrix_transpose(x)`. `array_namespace(x)` should be used instead
+  of `x.__array_namespace__`.
 
 - Value-based casting for scalars will be in effect unless explicitly disabled
   with the environment variable `NPY_PROMOTION_STATE=weak` or
@@ -41,7 +54,7 @@ NumPy has a few issues:
 If any of these are an issue, it is recommended to bump your minimum NumPy
 version.
 
-## PyTorch
+## [PyTorch](https://pytorch.org/)
 
 - Like NumPy/CuPy, we do not wrap the `torch.Tensor` object. It is missing the
   `__array_namespace__` and `to_device` methods, so the corresponding helper
@@ -85,13 +98,14 @@ version.
 
 The minimum supported PyTorch version is 1.13.
 
-## JAX
+(jax-support)=
+## [JAX](https://jax.readthedocs.io/en/latest/)
 
 Unlike the other libraries supported here, JAX array API support is contained
 entirely in the JAX library. The JAX array API support is tracked at
 https://github.com/google/jax/issues/18353.
 
-## Dask
+## [Dask](https://www.dask.org/)
 
 If you're using dask with numpy, many of the same limitations that apply to numpy
 will also apply to dask. Besides those differences, other limitations include missing