diff --git a/.circleci/config.yml b/.circleci/config.yml
index cb1031906..829dcbb64 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -5,7 +5,7 @@ _defaults: &defaults
docker:
# CircleCI maintains a library of pre-built images
# documented at https://circleci.com/docs/2.0/circleci-images/
- - image: circleci/python:3.7.0
+ - image: circleci/python:3.8.0
working_directory: ~/repo
jobs:
diff --git a/.gitignore b/.gitignore
index a740a2929..dfedda47f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,5 @@ spec/_build/
build/
.vscode/
node_modules/
+__pycache__/
+*.pyc
\ No newline at end of file
diff --git a/requirements.txt b/requirements.txt
index 5df0b2504..4741c6dc8 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,4 +1,4 @@
-sphinx==3.1.1
+sphinx==4.3.0
sphinx-material==0.0.30
myst-parser
sphinx_markdown_tables
diff --git a/spec/API_specification/signatures/__init__.py b/spec/API_specification/signatures/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/spec/API_specification/signatures/_types.py b/spec/API_specification/signatures/_types.py
new file mode 100644
index 000000000..6c0b5b85a
--- /dev/null
+++ b/spec/API_specification/signatures/_types.py
@@ -0,0 +1,40 @@
+"""
+This file defines the types for type annotations.
+
+The type variables should be replaced with the actual types for a given
+library, e.g., for NumPy TypeVar('array') would be replaced with ndarray.
+"""
+
+from dataclasses import dataclass
+from typing import Any, List, Literal, Optional, Sequence, Tuple, TypeVar, Union
+
+array = TypeVar('array')
+device = TypeVar('device')
+dtype = TypeVar('dtype')
+SupportsDLPack = TypeVar('SupportsDLPack')
+SupportsBufferProtocol = TypeVar('SupportsBufferProtocol')
+PyCapsule = TypeVar('PyCapsule')
+# ellipsis cannot actually be imported from anywhere, so include a dummy here
+# to keep pyflakes happy. https://github.com/python/typeshed/issues/3556
+ellipsis = TypeVar('ellipsis')
+
+@dataclass
+class finfo_object:
+ bits: int
+ eps: float
+ max: float
+ min: float
+ smallest_normal: float
+
+@dataclass
+class iinfo_object:
+ bits: int
+ max: int
+ min: int
+
+# This should really be recursive, but that isn't supported yet.
+NestedSequence = Sequence[Sequence[Any]]
+
+__all__ = ['Any', 'List', 'Literal', 'NestedSequence', 'Optional',
+'PyCapsule', 'SupportsBufferProtocol', 'SupportsDLPack', 'Tuple', 'Union',
+'array', 'device', 'dtype', 'ellipsis', 'finfo_object', 'iinfo_object']
\ No newline at end of file
diff --git a/spec/API_specification/signatures/sorting_functions.py b/spec/API_specification/signatures/sorting_functions.py
new file mode 100644
index 000000000..715a3e817
--- /dev/null
+++ b/spec/API_specification/signatures/sorting_functions.py
@@ -0,0 +1,45 @@
+from ._types import array
+
+def argsort(x: array, /, *, axis: int = -1, descending: bool = False, stable: bool = True) -> array:
+ """
+ Returns the indices that sort an array ``x`` along a specified axis.
+
+ Parameters
+ ----------
+ x : array
+ input array.
+ axis: int
+ axis along which to sort. If set to ``-1``, the function must sort along the last axis. Default: ``-1``.
+ descending: bool
+ sort order. If ``True``, the returned indices sort ``x`` in descending order (by value). If ``False``, the returned indices sort ``x`` in ascending order (by value). Default: ``False``.
+ stable: bool
+ sort stability. If ``True``, the returned indices must maintain the relative order of ``x`` values which compare as equal. If ``False``, the returned indices may or may not maintain the relative order of ``x`` values which compare as equal (i.e., the relative order of ``x`` values which compare as equal is implementation-dependent). Default: ``True``.
+
+ Returns
+ -------
+ out : array
+ an array of indices. The returned array must have the same shape as ``x``. The returned array must have the default array index data type.
+ """
+
+def sort(x: array, /, *, axis: int = -1, descending: bool = False, stable: bool = True) -> array:
+ """
+ Returns a sorted copy of an input array ``x``.
+
+ Parameters
+ ----------
+ x: array
+ input array.
+ axis: int
+ axis along which to sort. If set to ``-1``, the function must sort along the last axis. Default: ``-1``.
+ descending: bool
+ sort order. If ``True``, the array must be sorted in descending order (by value). If ``False``, the array must be sorted in ascending order (by value). Default: ``False``.
+ stable: bool
+ sort stability. If ``True``, the returned array must maintain the relative order of ``x`` values which compare as equal. If ``False``, the returned array may or may not maintain the relative order of ``x`` values which compare as equal (i.e., the relative order of ``x`` values which compare as equal is implementation-dependent). Default: ``True``.
+
+ Returns
+ -------
+ out : array
+ a sorted array. The returned array must have the same data type and shape as ``x``.
+ """
+
+__all__ = ['argsort', 'sort']
\ No newline at end of file
diff --git a/spec/API_specification/sorting_functions.md b/spec/API_specification/sorting_functions.md
deleted file mode 100644
index fd205fbe9..000000000
--- a/spec/API_specification/sorting_functions.md
+++ /dev/null
@@ -1,81 +0,0 @@
-# Sorting Functions
-
-> Array API specification for sorting functions.
-
-A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions.
-
-- 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.
-- Unless stated otherwise, functions must support the data types defined in {ref}`data-types`.
-
-```{note}
-For floating-point input arrays, the sort order of NaNs and signed zeros is unspecified and thus implementation-dependent.
-
-Implementations may choose to sort signed zeros (`-0 < +0`) or may choose to rely solely on value equality (`==`).
-
-Implementations may choose to sort NaNs (e.g., to the end or to the beginning of a returned array) or leave them in-place. Should an implementation sort NaNs, the sorting convention should be clearly documented in the conforming implementation's documentation.
-
-While defining a sort order for IEEE 754 floating-point numbers is recommended in order to facilitate reproducible and consistent sort results, doing so is not currently required by this specification.
-```
-
-## Objects in API
-
-
-
-(function-argsort)=
-### argsort(x, /, *, axis=-1, descending=False, stable=True)
-
-Returns the indices that sort an array `x` along a specified axis.
-
-#### Parameters
-
-- **x**: _<array>_
-
- - input array.
-
-- **axis**: _int_
-
- - axis along which to sort. If set to `-1`, the function must sort along the last axis. Default: `-1`.
-
-- **descending**: _bool_
-
- - sort order. If `True`, the returned indices sort `x` in descending order (by value). If `False`, the returned indices sort `x` in ascending order (by value). Default: `False`.
-
-- **stable**: _bool_
-
- - sort stability. If `True`, the returned indices must maintain the relative order of `x` values which compare as equal. If `False`, the returned indices may or may not maintain the relative order of `x` values which compare as equal (i.e., the relative order of `x` values which compare as equal is implementation-dependent). Default: `True`.
-
-#### Returns
-
-- **out**: _<array>_
-
- - an array of indices. The returned array must have the same shape as `x`. The returned array must have the default array index data type.
-
-(function-sort)=
-### sort(x, /, *, axis=-1, descending=False, stable=True)
-
-Returns a sorted copy of an input array `x`.
-
-#### Parameters
-
-- **x**: _<array>_
-
- - input array.
-
-- **axis**: _int_
-
- - axis along which to sort. If set to `-1`, the function must sort along the last axis. Default: `-1`.
-
-- **descending**: _bool_
-
- - sort order. If `True`, the array must be sorted in descending order (by value). If `False`, the array must be sorted in ascending order (by value). Default: `False`.
-
-- **stable**: _bool_
-
- - sort stability. If `True`, the returned array must maintain the relative order of `x` values which compare as equal. If `False`, the returned array may or may not maintain the relative order of `x` values which compare as equal (i.e., the relative order of `x` values which compare as equal is implementation-dependent). Default: `True`.
-
-#### Returns
-
-- **out**: _<array>_
-
- - a sorted array. The returned array must have the same data type and shape as `x`.
diff --git a/spec/API_specification/sorting_functions.rst b/spec/API_specification/sorting_functions.rst
new file mode 100644
index 000000000..da0ff99d1
--- /dev/null
+++ b/spec/API_specification/sorting_functions.rst
@@ -0,0 +1,34 @@
+Sorting Functions
+=================
+
+ Array API specification for sorting functions.
+
+A conforming implementation of the array API standard must provide and support the following functions adhering to the following conventions.
+
+* Positional parameters must be `positional-only `_ 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 `_ arguments.
+* Unless stated otherwise, functions must support the data types defined in :ref:`data-types`.
+
+.. note::
+
+ For floating-point input arrays, the sort order of NaNs and signed zeros is unspecified and thus implementation-dependent.
+
+ Implementations may choose to sort signed zeros (``-0 < +0``) or may choose to rely solely on value equality (``==``).
+
+ Implementations may choose to sort NaNs (e.g., to the end or to the beginning of a returned array) or leave them in-place. Should an implementation sort NaNs, the sorting convention should be clearly documented in the conforming implementation's documentation.
+
+ While defining a sort order for IEEE 754 floating-point numbers is recommended in order to facilitate reproducible and consistent sort results, doing so is not currently required by this specification.
+
+.. currentmodule:: signatures.sorting_functions
+
+Objects in API
+--------------
+..
+ NOTE: please keep the functions in alphabetical order
+
+.. autosummary::
+ :toctree: generated
+ :template: method.rst
+
+ argsort
+ sort
diff --git a/spec/_templates/method.rst b/spec/_templates/method.rst
new file mode 100644
index 000000000..3a85f2879
--- /dev/null
+++ b/spec/_templates/method.rst
@@ -0,0 +1,5 @@
+.. currentmodule:: {{ module }}
+
+{{ name.split('.')[-1] | underline }}
+
+.. autofunction:: {{ name }}
diff --git a/spec/conf.py b/spec/conf.py
index ffb1e94a2..5370da268 100644
--- a/spec/conf.py
+++ b/spec/conf.py
@@ -10,11 +10,10 @@
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
+import os
+import sys
import sphinx_material
+sys.path.insert(0, os.path.abspath('./API_specification'))
# -- Project information -----------------------------------------------------
@@ -38,8 +37,16 @@
'sphinx.ext.todo',
'sphinx_markdown_tables',
'sphinx_copybutton',
+ 'sphinx.ext.autosummary',
+ 'sphinx.ext.napoleon',
+ 'sphinx.ext.autodoc',
]
+autosummary_generate = True
+autodoc_typehints = 'signature'
+add_module_names = False
+napoleon_custom_sections = [('Returns', 'params_style')]
+
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -145,3 +152,14 @@
"dudir": ("http://docutils.sourceforge.net/docs/ref/rst/" "directives.html#%s", ""),
"pypa": ("https://packaging.python.org/%s", ""),
}
+
+
+def process_signature(app, what, name, obj, options, signature, return_annotation):
+ if signature:
+ signature = signature.replace("signatures._types.", "")
+ if return_annotation:
+ return_annotation = return_annotation.replace("signatures._types.", "")
+ return signature, return_annotation
+
+def setup(app):
+ app.connect("autodoc-process-signature", process_signature)
\ No newline at end of file