Transform sorting function specification file from Markdown to RST (#333)

* Transform sorting functions from md to rst file

* Fix the warning message

* Add autosummary with signatures for the sorting functions

* Bump CI python to 3.8

* Complete signatures and add types files

* Remove module names and add autodoc typehints

* Bump Sphinx version

* Remove module import from signature and return annonation

* Add jinja template for autosummary

* Put return section style as parameters and remove return type section

Author: steff456

.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

requirements.txt

@@ -1,4 +1,4 @@
-sphinx==3.1.1
+sphinx==4.3.0
 sphinx-material==0.0.30
 myst-parser
 sphinx_markdown_tables

spec/API_specification/signatures/__init__.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']

spec/API_specification/signatures/_types.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']

spec/API_specification/signatures/sorting_functions.py

@@ -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 <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
+   :template: method.rst
+
+   argsort
+   sort

spec/API_specification/sorting_functions.md

@@ -0,0 +1,5 @@
+.. currentmodule:: {{ module }}
+
+{{ name.split('.')[-1] | underline }}
+
+.. autofunction:: {{ name }}

spec/API_specification/sorting_functions.rst

@@ -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)