Replace recommonmark with MyST, fix all Sphinx issues

requirements.txt

@@ -1,5 +1,5 @@
 sphinx==3.1.1
 sphinx-material==0.0.30
-recommonmark
+myst-parser
 sphinx_markdown_tables
 sphinx_copybutton

spec/API_specification/broadcasting.md

@@ -1,4 +1,4 @@
-.. _broadcasting:
+(broadcasting)=
 
 # Broadcasting
 

spec/API_specification/constants.md

@@ -6,6 +6,8 @@ A conforming implementation of the array API standard must provide and support t
 
 <!-- NOTE: please keep the constants in alphabetical order -->
 
+## Objects in API
+
 ### <a name="e" href="#e">#</a> e
 
 Euler's constant.

spec/API_specification/creation_functions.md

@@ -7,6 +7,8 @@ A conforming implementation of the array API standard must provide and support t
 -   Positional parameters must be [positional-only](https://www.python.org/dev/peps/pep-0570/) parameters. Positional-only parameters have no externally-usable name. When a function accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order.
 -   Optional parameters must be [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments.
 
+## Objects in API
+
 <!-- NOTE: please keep the functions in alphabetical order -->
 
 ### <a name="arange" href="#arange">#</a> arange(start, /, *, stop=None, step=1, dtype=None)
@@ -23,9 +25,10 @@ Returns evenly spaced values within the half-open interval `[start, stop)` as a
 
     -   the end of the interval. Default: `None`.
 
-.. note::
+```{note}
 
-    This function cannot guarantee that the interval does not include the `stop` value in those cases where `step` is not an integer and floating-point rounding errors affect the length of the output array.
+This function cannot guarantee that the interval does not include the `stop` value in those cases where `step` is not an integer and floating-point rounding errors affect the length of the output array.
+```
 
 -   **step**: _Union\[ int, float ]_
 

spec/API_specification/data_types.md

@@ -1,33 +1,37 @@
-.. _data-types:
+(data-types)=
 
 # Data Types
 
 > Array API specification for supported data types.
 
 A conforming implementation of the array API standard must provide and support the following data types.
 
-.. note::
+```{note}
 
-    Data types ("dtypes") are objects that can be used as `dtype` specifiers in functions and methods (e.g., `zeros((2, 3), dtype=float32)`). A conforming implementation may add methods or attributes to data type objects; however, these methods and attributes are not included in this specification.
+Data types ("dtypes") are objects that can be used as `dtype` specifiers in functions and methods (e.g., `zeros((2, 3), dtype=float32)`). A conforming implementation may add methods or attributes to data type objects; however, these methods and attributes are not included in this specification.
+```
 
-.. note::
+```{note}
 
-    Implementations may provide other ways to specify data types (e.g.,
-    `zeros((2, 3), dtype='f4')`); however, these are not included in this specification.
+Implementations may provide other ways to specify data types (e.g.,
+`zeros((2, 3), dtype='f4')`); however, these are not included in this specification.
+```
 
 A conforming implementation of the array API standard may provide and support additional data types beyond those described in this specification.
 
 A conforming implementation of the array API standard must define a default floating-point data type (either `float32` or `float64`).
 
-.. note::
+```{note}
 
-    The default floating-point data type should be clearly defined in a conforming library's documentation.
+The default floating-point data type should be clearly defined in a conforming library's documentation.
+```
 
 A conforming implementation of the array API standard must define a default data type for an array index (either `int32` or `int64`).
 
-.. note::
+```{note}
 
-    The default array index data type should be clearly defined in a conforming library's documentation.
+The default array index data type should be clearly defined in a conforming library's documentation.
+```
 
 
 ## bool

spec/API_specification/function_and_method_signatures.md

@@ -1,4 +1,4 @@
-.. _function-and-method-signatures:
+(function-and-method-signatures)=
 
 # Function and method signatures
 
@@ -13,12 +13,13 @@ Function signatures in this standard adhere to the following:
    _Rationale: existing libraries have incompatible conventions, and using names
    of positional parameters is not normal/recommended practice._
 
-   .. note::
+    ```{note}
 
-       Positional-only parameters are only available in Python >= 3.8. Libraries
-       still supporting 3.7 or 3.6 may consider making the API standard-compliant
-       namespace >= 3.8. Alternatively, they can add guidance to their users in the
-       documentation to use the functions as if they were positional-only. 
+    Positional-only parameters are only available in Python >= 3.8. Libraries
+    still supporting 3.7 or 3.6 may consider making the API standard-compliant
+    namespace >= 3.8. Alternatively, they can add guidance to their users in the
+    documentation to use the functions as if they were positional-only. 
+    ```
 
 2. Optional parameters must be
    [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments.

spec/API_specification/index.rst

@@ -12,7 +12,6 @@ API specification
    indexing
    data_types
    type_promotion
-   casting
    broadcasting
    creation_functions
    manipulation_functions

spec/API_specification/indexing.md

@@ -1,4 +1,4 @@
-.. _indexing:
+(indexing)=
 
 # Indexing
 
@@ -16,21 +16,24 @@ To index a single array axis, an array must support standard Python indexing rul
 
 -   **Valid** nonnegative indices must reside on the half-open interval `[0, n)`.
 
-    .. note::
+    ```{note}
 
-        This specification does not require bounds checking. The behavior for out-of-bounds integer indices is left unspecified.
+    This specification does not require bounds checking. The behavior for out-of-bounds integer indices is left unspecified.
+    ```
 
 -   Negative indices must count backward from the last array index, starting from `-1` (i.e., negative-one-based indexing, where `-1` refers to the last array index).
 
-    .. note::
+    ```{note}
 
-        A negative index `j` is equivalent to `n-j`; the former is syntactic sugar for the latter, providing a shorthand for indexing elements that would otherwise need to be specified in terms of the axis (dimension) size.
+    A negative index `j` is equivalent to `n-j`; the former is syntactic sugar for the latter, providing a shorthand for indexing elements that would otherwise need to be specified in terms of the axis (dimension) size.
+    ```
 
 -   **Valid** negative indices must reside on the closed interval `[-n, -1]`.
 
-    .. note::
+    ```{note}
 
-        This specification does not require bounds checking. The behavior for out-of-bounds integer indices is left unspecified.
+    This specification does not require bounds checking. The behavior for out-of-bounds integer indices is left unspecified.
+    ```
 
 -   A negative index `j` is related to a zero-based nonnegative index `i` via `i = n+j`.
 
@@ -56,9 +59,10 @@ A[i::k]
 A[i:j:k]
 ```
 
-.. note::
+```{note}
 
-    Slice syntax can be equivalently achieved using the Python built-in [`slice()`](https://docs.python.org/3/library/functions.html#slice) API. From the perspective from `A`, the behavior of `A[i:j:k]` and `A[slice(i, j, k)]` is indistinguishable (i.e., both retrieve the same set of items from `__getitem__`).
+Slice syntax can be equivalently achieved using the Python built-in [`slice()`](https://docs.python.org/3/library/functions.html#slice) API. From the perspective from `A`, the behavior of `A[i:j:k]` and `A[slice(i, j, k)]` is indistinguishable (i.e., both retrieve the same set of items from `__getitem__`).
+```
 
 Using a slice to index a single array axis must select `m` elements with index values
 
@@ -84,13 +88,15 @@ such that
 j > i + (m-1)k
 ```
 
-.. note::
+```{note}
 
-    For `i` on the interval `[0, n)` (where `n` is the axis size), `j` on the interval `(0, n]`, `i` less than `j`, and positive step `k`, a starting index `i` is **always** included, while the stopping index `j` is **always** excluded. This preserves `x[:i]+x[i:]` always being equal to `x`.
+For `i` on the interval `[0, n)` (where `n` is the axis size), `j` on the interval `(0, n]`, `i` less than `j`, and positive step `k`, a starting index `i` is **always** included, while the stopping index `j` is **always** excluded. This preserves `x[:i]+x[i:]` always being equal to `x`.
+```
 
-.. note::
+```{note}
 
-    Using a slice to index into a single array axis should select the same elements as using a slice to index a Python list of the same size.
+Using a slice to index into a single array axis should select the same elements as using a slice to index a Python list of the same size.
+```
 
 Slice syntax must have the following defaults. Let `n` be the axis (dimension) size.
 
@@ -106,27 +112,30 @@ Using a slice to index a single array axis must adhere to the following rules. L
 
 -   Indexing via `:` and `::` must be equivalent and have defaults derived from the rules above. Both `:` and `::` indicate to select all elements along a single axis (dimension).
 
-.. note::
+```{note}
 
-    This specification does not require "clipping" out-of-bounds indices (i.e., requiring the starting and stopping indices `i` and `j` be bound by `0` and `n`, respectively).
+This specification does not require "clipping" out-of-bounds indices (i.e., requiring the starting and stopping indices `i` and `j` be bound by `0` and `n`, respectively).
 
-    _Rationale: this is consistent with bounds checking for integer indexing; the behavior of out-of-bounds indices is left unspecified. Implementations may choose to clip, raise an exception, return junk values, or some other behavior depending on device requirements and performance considerations._
+_Rationale: this is consistent with bounds checking for integer indexing; the behavior of out-of-bounds indices is left unspecified. Implementations may choose to clip, raise an exception, return junk values, or some other behavior depending on device requirements and performance considerations._
+```
 
-.. note::
+```{note}
 
-    This specification leaves unspecified the behavior of indexing a single array axis with an out-of-bounds slice (i.e., a slice which does not select any array axis elements).
+This specification leaves unspecified the behavior of indexing a single array axis with an out-of-bounds slice (i.e., a slice which does not select any array axis elements).
 
-    _Rationale: this is consistent with bounds checking for integer indexing; the behavior of out-of-bounds indices is left unspecified. Implementations may choose to return an empty array (whose axis (dimension) size along the indexed axis is `0`), raise an exception, or some other behavior depending on device requirements and performance considerations._
+_Rationale: this is consistent with bounds checking for integer indexing; the behavior of out-of-bounds indices is left unspecified. Implementations may choose to return an empty array (whose axis (dimension) size along the indexed axis is `0`), raise an exception, or some other behavior depending on device requirements and performance considerations._
+```
 
 ## Multi-axis Indexing
 
 Multi-dimensional arrays must extend the concept of single-axis indexing to multiple axes by applying single-axis indexing rules along each axis (dimension) and supporting the following additional rules. Let `N` be the number of dimensions ("rank") of a multi-dimensional array `A`.
 
 -   Each axis may be independently indexed via single-axis indexing by providing a comma-separated sequence ("selection tuple") of single-axis indexing expressions (e.g., `A[:, 2:10, :, 5]`).
 
-    .. note::
+    ```{note}
 
-        In Python, `x[(exp1, exp2, ..., expN)]` is equivalent to `x[exp1, exp2, ..., expN]`; the latter is syntactic sugar for the former.
+    In Python, `x[(exp1, exp2, ..., expN)]` is equivalent to `x[exp1, exp2, ..., expN]`; the latter is syntactic sugar for the former.
+    ```
 
 -   Providing a single nonnegative integer `i` as a single-axis index must index the same elements as the slice `i:i+1`.
 
@@ -144,21 +153,23 @@ Multi-dimensional arrays must extend the concept of single-axis indexing to mult
 
 -   The result of multi-axis indexing must be an array of the same data type as the indexed array.
 
-.. note::
+```{note}
 
-    This specification leaves unspecified the behavior of providing a slice which attempts to select elements along a particular axis, but whose starting index is out-of-bounds.
+This specification leaves unspecified the behavior of providing a slice which attempts to select elements along a particular axis, but whose starting index is out-of-bounds.
 
-    _Rationale: this is consistent with bounds-checking for single-axis indexing. An implementation may choose to set the axis (dimension) size of the result array to `0`, raise an exception, return junk values, or some other behavior depending on device requirements and performance considerations._
+_Rationale: this is consistent with bounds-checking for single-axis indexing. An implementation may choose to set the axis (dimension) size of the result array to `0`, raise an exception, return junk values, or some other behavior depending on device requirements and performance considerations._
+```
 
 ## Boolean Array Indexing
 
 An array must support indexing via a **single** `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)]`.
 
-    .. note::
+    ```{note}
 
-        For example, if `N == M == 2`, indexing `A` via a boolean array `B` will return a one-dimensional array whose size is equal to the number of `True` elements in `B`.
+    For example, if `N == M == 2`, indexing `A` via a boolean array `B` will return a one-dimensional array whose size is equal to the number of `True` elements in `B`.
+    ```
 
 -   If `N < M`, then an `IndexError` exception must be raised.
 

spec/API_specification/linear_algebra_functions.md

@@ -6,11 +6,13 @@ A conforming implementation of the array API standard must provide and support t
 
 -   Positional parameters must be [positional-only](https://www.python.org/dev/peps/pep-0570/) parameters. Positional-only parameters have no externally-usable name. When a function accepting positional-only parameters is called, positional arguments are mapped to these parameters based solely on their order.
 -   Optional parameters must be [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments.
--   Broadcasting semantics must follow the semantics defined in :ref:`broadcasting`.
--   Unless stated otherwise, functions must support the data types defined in :ref:`data-types`.
--   Unless stated otherwise, functions must adhere to the type promotion rules defined in :ref:`type-promotion`.
+-   Broadcasting semantics must follow the semantics defined in {ref}`broadcasting`.
+-   Unless stated otherwise, functions must support the data types defined in {ref}`data-types`.
+-   Unless stated otherwise, functions must adhere to the type promotion rules defined in {ref}`type-promotion`.
 -   Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019.
 
+## Objects in API
+
 <!-- NOTE: please keep the functions in alphabetical order -->
 
 ### <a name="cholesky" href="#cholesky">#</a> cholesky()
@@ -39,7 +41,7 @@ Returns the cross product of 3-element vectors. If `x1` and `x2` are multi-dimen
 
 -   **out**: _&lt;array&gt;_
 
-    -   an array containing the cross products. The returned array must have a data type determined by :ref:`type-promotion` rules.
+    -   an array containing the cross products. The returned array must have a data type determined by {ref}`type-promotion` rules.
 
 ### <a name="det" href="#det">#</a> det(x, /)
 
@@ -55,7 +57,7 @@ Returns the determinant of a square matrix (or stack of square matrices) `x`.
 
 -   **out**: _&lt;array&gt;_
 
-    -   if `x` is a two-dimensional array, a zero-dimensional array containing the determinant; otherwise, a non-zero dimensional array containing the determinant for each square matrix. The returned array must have a data type determined by :ref:`type-promotion` rules.
+    -   if `x` is a two-dimensional array, a zero-dimensional array containing the determinant; otherwise, a non-zero dimensional array containing the determinant for each square matrix. The returned array must have a data type determined by {ref}`type-promotion` rules.
 
 ### <a name="diagonal" href="#diagonal">#</a> diagonal(x, /, *, axis1=0, axis2=1, offset=0)
 
@@ -165,7 +167,7 @@ Computes the matrix or vector norm of `x`.
 
 -   **keepdims**: _bool_
 
-    -   If `True`, the axes (dimensions) specified by `axis` must be included in the result as singleton dimensions, and, accordingly, the result must be compatible with the input array (see :ref:`broadcasting`). Otherwise, if `False`, the axes (dimensions) specified by `axis` must not be included in the result. Default: `False`.
+    -   If `True`, the axes (dimensions) specified by `axis` must be included in the result as singleton dimensions, and, accordingly, the result must be compatible with the input array (see {ref}`broadcasting`). Otherwise, if `False`, the axes (dimensions) specified by `axis` must not be included in the result. Default: `False`.
 
 -   **ord**: _Optional\[ int, float, Literal\[ inf, -inf, 'fro', 'nuc' ] ]_
 
@@ -235,7 +237,7 @@ Computes the outer product of two vectors `x1` and `x2`.
 
 -   **out**: _&lt;array&gt;_
 
-    -   a two-dimensional array containing the outer product and whose shape is `NxM`. The returned array must have a data type determined by :ref:`type-promotion` rules.
+    -   a two-dimensional array containing the outer product and whose shape is `NxM`. The returned array must have a data type determined by {ref}`type-promotion` rules.
 
 ### <a name="pinv" href="#pinv">#</a> pinv()