PR: Transform sorting functions from md to rst file

.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:

.gitignore

@@ -2,3 +2,5 @@ spec/_build/
 build/
 .vscode/
 node_modules/
+__pycache__/
+*.pyc

spec/API_specification/signatures/_sorting_functions.py

@@ -0,0 +1,43 @@
+def argsort(x, /, *, axis:int = -1, descending:bool = False, stable:bool = 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.
+    """
+    pass
+
+def sort(x, /, *, axis:int = -1, descending:bool = False, stable: bool = 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``.
+    """
+    pass

spec/API_specification/sorting_functions.rst

@@ -0,0 +1,33 @@
+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.
+
+.. currentmodule:: signatures._sorting_functions
+
+Objects in API
+--------------
+..
+  NOTE: please keep the functions in alphabetical order
+
+.. autosummary::
+   :toctree: generated
+
+   argsort
+   sort

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,13 @@
     'sphinx.ext.todo',
     'sphinx_markdown_tables',
     'sphinx_copybutton',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
 ]
 
+autosummary_generate = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']