Add a note on adding complex64/128 in a future version (#105)

This introduces a new "Future extension" admonition, which
uses the MyST "colon fence" (requires a newer version of MyST).

Closes gh-102

Author: rgommers

spec/API_specification/data_types.md

@@ -6,31 +6,11 @@
 
 A conforming implementation of the array API standard must provide and support the following data types.
 
-```{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.
-```
-
-```{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.
-```
-
-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`).
+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`).
 
 ```{note}
 
-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}
-
-The default array index data type should be clearly defined in a conforming library's documentation.
+The default floating-point and array index integer data types should be clearly defined in a conforming library's documentation.
 ```
 
 
@@ -77,3 +57,24 @@ IEEE 754 single-precision (32-bit) binary floating-point number (see IEEE 754-20
 ## float64
 
 IEEE 754 double-precision (64-bit) binary floating-point number (see IEEE 754-2019).
+
+
+:::{admonition} Future extension
+:class: hint
+It is expected that in the next version of this standard, `complex64` and `complex128`
+dtypes will be added, with these casting rules (will be added to {ref}`type-promotion`):
+
+![Type promotion diagram for complex dtypes in next version](/_static/images/dtype_promotion_complex.png)
+
+See [array-api/issues/102](https://github.com/data-apis/array-api/issues/102)
+for more details.
+:::
+
+```{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.
+
+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.
+```

spec/_static/images/dtype_promotion_complex.png

@@ -50,6 +50,7 @@
 
 # MyST options
 myst_heading_anchors = 3
+myst_enable_extensions = ["colon_fence"]
 
 # -- Options for HTML output -------------------------------------------------