Replace recommonmark with MyST, fix all Sphinx issues (#72)

Author: rgommers

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/array_object.md

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

spec/API_specification/broadcasting.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/casting.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/constants.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/creation_functions.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/data_types.md

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