PR: Add note for functions that are not compatible with static memory allocation

.github/workflows/pages.yml

@@ -1,9 +1,9 @@
-on: 
+on:
   push:
     branches:
       - main
   pull_request:
-    branches: 
+    branches:
     - "**"
 jobs:
   run:
@@ -33,9 +33,7 @@ jobs:
         if-no-files-found: error
     - name: Deploy
       if: ${{ github.ref == 'refs/heads/main'}}
-      uses: JamesIves/[email protected]
-      env:
-        ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        BASE_BRANCH: main # The branch the action should deploy from.
-        BRANCH: gh-pages # The branch the action should deploy to.
-        FOLDER: build
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./build

spec/API_specification/constants.md

@@ -2,7 +2,9 @@
 
 > Array API specification for constants.
 
-A conforming implementation of the array API standard must provide and support the following constants.
+A conforming implementation of the array API standard must provide and support the following constants adhering to the following conventions.
+
+-   Each constant must have a Python floating-point data type (i.e., `float`) and be provided as a Python scalar value.
 
 <!-- NOTE: please keep the constants in alphabetical order -->
 
@@ -11,7 +13,7 @@ A conforming implementation of the array API standard must provide and support t
 (constant-e)=
 ### e
 
-Euler's constant.
+IEEE 754 floating-point representation of Euler's constant.
 
 ```text
 e = 2.71828182845904523536028747135266249775724709369995...
@@ -30,7 +32,7 @@ IEEE 754 floating-point representation of Not a Number (`NaN`).
 (constant-pi)=
 ### pi
 
-The mathematical constant `π`.
+IEEE 754 floating-point representation of the mathematical constant `π`.
 
 ```text
 pi = 3.1415926535897932384626433...

spec/API_specification/creation_functions.md

@@ -12,7 +12,7 @@ A conforming implementation of the array API standard must provide and support t
 <!-- NOTE: please keep the functions in alphabetical order -->
 
 (function-arange)=
-### arange(start, /, *, stop=None, step=1, dtype=None, device=None)
+### arange(start, /, stop=None, step=1, *, dtype=None, device=None)
 
 Returns evenly spaced values within the half-open interval `[start, stop)` as a one-dimensional array.
 
@@ -33,11 +33,11 @@ This function cannot guarantee that the interval does not include the `stop` val
 
 -   **step**: _Union\[ int, float ]_
 
-    -   the distance between two adjacent elements (`out[i+1] - out[i]`). Default: `1`.
+    -   the distance between two adjacent elements (`out[i+1] - out[i]`). Must not be `0`; may be negative, this results in an empty array if `stop >= start`. Default: `1`.
 
 -   **dtype**: _Optional\[ &lt;dtype&gt; ]_
 
-    -   output array data type. If `dtype` is `None`, the output array data type must be the default floating-point data type. Default: `None`.
+    -   output array data type. If `dtype` is `None`, the output array data type must be inferred from `start`, `stop` and `step`. If those are all integers, the output array dtype must be the default integer dtype; if one or more have type `float`, then the output array dtype must be the default floating-point data type. Default: `None`.
 
 -   **device**: _Optional\[ &lt;device&gt; ]_
 
@@ -47,7 +47,7 @@ This function cannot guarantee that the interval does not include the `stop` val
 
 -   **out**: _&lt;array&gt;_
 
-    -   a one-dimensional array containing evenly spaced values. The length of the output array must be `ceil((stop-start)/step)`.
+    -   a one-dimensional array containing evenly spaced values. The length of the output array must be `ceil((stop-start)/step)` if `stop - start` and `step` have the same sign, and length 0 otherwise.
 
 
 (function-asarray)=
@@ -68,7 +68,7 @@ Convert the input to an array.
 
 -   **dtype**: _Optional\[ &lt;dtype&gt; ]_
 
-    -   output array data type. If `dtype` is `None`, the output array data type must be inferred from the data type(s) in `obj`. Default: `None`.
+    -   output array data type. If `dtype` is `None`, the output array data type must be inferred from the data type(s) in `obj`. If all input values are Python scalars, then if they're all `bool` the output dtype will be `bool`; if they're a mix of `bool`s and `int` the output dtype will be the default integer data type; if they contain `float`s the output dtype will be the default floating-point data type. Default: `None`.
 
 -   **device**: _Optional\[ &lt;device&gt; ]_
 
@@ -86,7 +86,7 @@ Convert the input to an array.
 
 
 (function-empty)=
-### empty(shape, /, *, dtype=None, device=None)
+### empty(shape, *, dtype=None, device=None)
 
 Returns an uninitialized array having a specified `shape`.
 
@@ -136,19 +136,19 @@ Returns an uninitialized array with the same `shape` as an input array `x`.
     -   an array having the same shape as `x` and containing uninitialized data.
 
 (function-eye)=
-### eye(N, /, *, M=None, k=0, dtype=None, device=None)
+### eye(n_rows, n_cols=None, /, *, k=0, dtype=None, device=None)
 
 Returns a two-dimensional array with ones on the `k`th diagonal and zeros elsewhere.
 
 #### Parameters
 
--   **N**: _int_
+-   **n_rows**: _int_
 
     -   number of rows in the output array.
 
--   **M**: _Optional\[ int ]_
+-   **n_cols**: _Optional\[ int ]_
 
-    -   number of columns in the output array. If `None`, the default number of columns in the output array is `N`. Default: `None`.
+    -   number of columns in the output array. If `None`, the default number of columns in the output array is equal to `n_rows`. Default: `None`.
 
 -   **k**: _Optional\[ int ]_
 
@@ -190,7 +190,7 @@ Returns a new array containing the data from another (array) object with a `__dl
         ```
 
 (function-full)=
-### full(shape, fill_value, /, *, dtype=None, device=None)
+### full(shape, fill_value, *, dtype=None, device=None)
 
 Returns a new array having a specified `shape` and filled with `fill_value`.
 
@@ -206,7 +206,7 @@ Returns a new array having a specified `shape` and filled with `fill_value`.
 
 -   **dtype**: _Optional\[ &lt;dtype&gt; ]_
 
-    -   output array data type. If `dtype` is `None`, the output array data type must be the default floating-point data type. Default: `None`.
+    -   output array data type. If `dtype` is `None`, the output array data type must be inferred from `fill_value`. If it's an `int`, the output array dtype must be the default integer dtype; if it's a `float`, then the output array dtype must be the default floating-point data type; if it's a `bool` then the output array must have boolean dtype. Default: `None`.
 
 -   **device**: _Optional\[ &lt;device&gt; ]_
 
@@ -219,7 +219,7 @@ Returns a new array having a specified `shape` and filled with `fill_value`.
     -   an array where every element is equal to `fill_value`.
 
 (function-full_like)=
-### full_like(x, fill_value, /, *, dtype=None, device=None)
+### full_like(x, /, fill_value, *, dtype=None, device=None)
 
 Returns a new array filled with `fill_value` and having the same `shape` as an input array `x`.
 
@@ -235,7 +235,7 @@ Returns a new array filled with `fill_value` and having the same `shape` as an i
 
 -   **dtype**: _Optional\[ &lt;dtype&gt; ]_
 
-    -   output array data type. If `dtype` is `None`, the output array data type must be inferred from `x`. Default: `None`.
+    -   output array data type. If `dtype` is `None`, the output array data type must be inferred from `fill_value` (see {ref}`function-full`). Default: `None`.
 
 -   **device**: _Optional\[ &lt;device&gt; ]_
 
@@ -248,7 +248,7 @@ Returns a new array filled with `fill_value` and having the same `shape` as an i
     -   an array having the same shape as `x` and where every element is equal to `fill_value`.
 
 (function-linspace)=
-### linspace(start, stop, num, /, *, dtype=None, device=None, endpoint=True)
+### linspace(start, stop, /, num, *, dtype=None, device=None, endpoint=True)
 
 Returns evenly spaced numbers over a specified interval.
 
@@ -290,7 +290,7 @@ Returns evenly spaced numbers over a specified interval.
     -   a one-dimensional array containing evenly spaced values.
 
 (function-meshgrid)=
-### meshgrid(*arrays, /, *, indexing='xy')
+### meshgrid(*arrays, indexing='xy')
 
 Returns coordinate matrices from coordinate vectors.
 
@@ -302,26 +302,26 @@ Returns coordinate matrices from coordinate vectors.
 
 -    **indexing**: _str_
 
-    -   Cartesian 'xy' or matrix 'ij' indexing of output. If provided zero or one one-dimensional vector(s) (i.e., the zero- and one-dimensional cases, respectively), the `indexing` keyword has no effect and should be ignored. Default: `'xy'`.
+     -   Cartesian 'xy' or matrix 'ij' indexing of output. If provided zero or one one-dimensional vector(s) (i.e., the zero- and one-dimensional cases, respectively), the `indexing` keyword has no effect and should be ignored. Default: `'xy'`.
 
 #### Returns
 
 -    **out**: _List\[ &lt;array&gt;, ... ]_
 
-    -   list of N arrays, where `N` is the number of provided one-dimensional input arrays. Each returned array must have rank `N`. For `N` one-dimensional arrays having lengths `Ni = len(xi)`,
+     -   list of N arrays, where `N` is the number of provided one-dimensional input arrays. Each returned array must have rank `N`. For `N` one-dimensional arrays having lengths `Ni = len(xi)`,
 
-        -   if matrix indexing `ij`, then each returned array must have the shape `(N1, N2, N3, ..., Nn)`.
+         -   if matrix indexing `ij`, then each returned array must have the shape `(N1, N2, N3, ..., Nn)`.
 
-        -   if Cartesian indexing `xy`, then each returned array must have shape `(N2, N1, N3, ..., Nn)`.
+         -   if Cartesian indexing `xy`, then each returned array must have shape `(N2, N1, N3, ..., Nn)`.
 
-        Accordingly, for the two-dimensional case with input one-dimensional arrays of length `M` and `N`, if matrix indexing `ij`, then each returned array must have shape `(M, N)`, and, if Cartesian indexing `xy`, then each returned array must have shape `(N, M)`.
+         Accordingly, for the two-dimensional case with input one-dimensional arrays of length `M` and `N`, if matrix indexing `ij`, then each returned array must have shape `(M, N)`, and, if Cartesian indexing `xy`, then each returned array must have shape `(N, M)`.
 
-        Similarly, for the three-dimensional case with input one-dimensional arrays of length `M`, `N`, and `P`, if matrix indexing `ij`, then each returned array must have shape `(M, N, P)`, and, if Cartesian indexing `xy`, then each returned array must have shape `(N, M, P)`.
+         Similarly, for the three-dimensional case with input one-dimensional arrays of length `M`, `N`, and `P`, if matrix indexing `ij`, then each returned array must have shape `(M, N, P)`, and, if Cartesian indexing `xy`, then each returned array must have shape `(N, M, P)`.
 
-        The returned arrays must have a numeric data type determined by {ref}`type-promotion`.
+         The returned arrays must have a numeric data type determined by {ref}`type-promotion`.
 
 (function-ones)=
-### ones(shape, /, *, dtype=None, device=None)
+### ones(shape, *, dtype=None, device=None)
 
 Returns a new array having a specified `shape` and filled with ones.
 
@@ -371,7 +371,7 @@ Returns a new array filled with ones and having the same `shape` as an input arr
     -   an array having the same shape as `x` and filled with ones.
 
 (function-zeros)=
-### zeros(shape, /, *, dtype=None, device=None)
+### zeros(shape, *, dtype=None, device=None)
 
 Returns a new array having a specified `shape` and filled with zeros.
 

spec/API_specification/data_type_functions.md

@@ -7,14 +7,14 @@ A conforming implementation of the array API standard must provide and support t
 <!-- NOTE: please keep the constants in alphabetical order -->
 
 ## Objects in API
-(function-broadcast-arrays)=
-### broadcast_arrays(\*args, /)
+(function-broadcast_arrays)=
+### broadcast_arrays(*arrays)
 
 Broadcasts one or more arrays against one another.
 
 #### Parameters
 
--   **\*args**: _Sequence\[ &lt;array&gt; ]_
+-   **arrays**: _Sequence\[ &lt;array&gt; ]_
 
     -   arrays to broadcast.
 
@@ -24,8 +24,8 @@ Broadcasts one or more arrays against one another.
 
     -   a list of broadcasted arrays. Each array must have the same shape. Each array must have the same dtype as its corresponding input array.
 
-(function-broadcast-to)=
-### broadcast_to(x, shape, /)
+(function-broadcast_to)=
+### broadcast_to(x, /, shape)
 
 Broadcasts an array to a specified shape.
 
@@ -49,14 +49,14 @@ Broadcasts an array to a specified shape.
 
 -   if the array is incompatible with the specified shape (see {ref}`broadcasting`).
 
-(function-can-cast)=
-### can_cast(from, to, /)
+(function-can_cast)=
+### can_cast(from_, to, /)
 
 Determines if one data type can be cast to another data type according {ref}`type-promotion` rules.
 
 #### Parameters
 
--   **from**: _Union\[ &lt;dtype&gt;, &lt;array&gt;]_
+-   **from_**: _Union\[ &lt;dtype&gt;, &lt;array&gt;]_
 
     -   input data type or array from which to cast.
 

spec/API_specification/data_types.md

@@ -6,10 +6,9 @@
 
 A conforming implementation of the array API standard must provide and support the following data types.
 
-A conforming implementation of the array API standard must define a default floating-point data type (either `float32` or `float64`), as well as a default data type for an array index (either `int32` or `int64`).
+A conforming implementation of the array API standard must define a default floating-point data type (either `float32` or `float64`), as well as a default integer data type (`int32` or `int64`). These default data types must be the same across platforms. The default integer data type may vary depending on whether Python is 32-bit or 64-bit.
 
 ```{note}
-
 The default floating-point and array index integer data types should be clearly defined in a conforming library's documentation.
 ```
 

spec/API_specification/elementwise_functions.md

@@ -570,7 +570,7 @@ Computes the truth value of `x1_i == x2_i` for each element `x1_i` of the input
 
 -   **x2**: _<array>_
 
-    -   second input array. Must be compatible with `x1` (see {ref}`broadcasting`).
+    -   second input array. Must be compatible with `x1` (see {ref}`broadcasting`). May have any data type.
 
 #### Returns
 
@@ -946,11 +946,11 @@ For floating-point operands,
 
 -   **x1**: _<array>_
 
-    -   first input array.
+    -   first input array. Should have a floating-point data type.
 
 -   **x2**: _<array>_
 
-    -   second input array. Must be compatible with `x1` (see {ref}`broadcasting`).
+    -   second input array. Must be compatible with `x1` (see {ref}`broadcasting`). Should have a floating-point data type.
 
 #### Returns
 

spec/API_specification/indexing.md

@@ -160,6 +160,12 @@ _Rationale: this is consistent with bounds-checking for single-axis indexing. An
 
 ## Boolean Array Indexing
 
+:::{admonition} Data-dependent output shape
+:class: important
+
+For common boolean array use cases (e.g., using a dynamically-sized boolean array mask to filter the values of another array), the shape of the output array is data-dependent; hence, libraries that build array computation graphs (e.g., JAX, Dask, etc.) may find boolean array indexing difficult to implement. Accordingly, such libraries may choose to omit boolean array indexing. See {ref}`data-dependent-output-shapes` section for more details.
+:::
+
 An array must support indexing where the **sole index** is an `M`-dimensional boolean array `B` with shape `S1 = (s1, ..., sM)` according to the following rules. Let `A` be an `N`-dimensional array with shape `S2 = (s1, ..., sM, ..., sN)`.
 
 -   If `N >= M`, then `A[B]` must replace the first `M` dimensions of `A` with a single dimension having a size equal to the number of `True` elements in `B`. The values in the resulting array must be in row-major (C-style order); this is equivalent to `A[nonzero(B)]`.