From ee49db99e3b03296b4b985bae0bb2c918e03cfe1 Mon Sep 17 00:00:00 2001 From: Athan Date: Sun, 11 May 2025 22:36:21 -0700 Subject: [PATCH 1/3] docs: move notes below the fold and highlight RFC 2119 keywords --- .../_draft/sorting_functions.py | 42 ++++++++++--------- 1 file changed, 23 insertions(+), 19 deletions(-) diff --git a/src/array_api_stubs/_draft/sorting_functions.py b/src/array_api_stubs/_draft/sorting_functions.py index 2dc4ac410..d09f2aa11 100644 --- a/src/array_api_stubs/_draft/sorting_functions.py +++ b/src/array_api_stubs/_draft/sorting_functions.py @@ -10,24 +10,26 @@ def argsort( """ Returns the indices that sort an array ``x`` along a specified axis. - .. note:: - For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). - Parameters ---------- - x : array - input array. Should have a real-valued data type. + x: array + input array. *Should* have a real-valued data type. axis: int - axis along which to sort. If set to ``-1``, the function must sort along the last axis. Default: ``-1``. + 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``. + sort order. If ``True``, the returned indices *must* sort ``x`` in descending order (by value). If ``False``, the returned indices *must* 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``. + 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* 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. + 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. + + Notes + ----- + + - For backward compatibility, conforming implementations *may* support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). """ @@ -37,22 +39,24 @@ def sort( """ Returns a sorted copy of an input array ``x``. - .. note:: - For backward compatibility, conforming implementations may support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). - Parameters ---------- x: array - input array. Should have a real-valued data type. + input array. *Should* have a real-valued data type. axis: int - axis along which to sort. If set to ``-1``, the function must sort along the last axis. Default: ``-1``. + 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``. + 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``. + 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* 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``. + out: array + a sorted array. The returned array *must* have the same data type and shape as ``x``. + + Notes + ----- + + - For backward compatibility, conforming implementations *may* support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). """ From c449b558ffca210f6fd48c977ad58fba960a23ee Mon Sep 17 00:00:00 2001 From: Athan Date: Sun, 11 May 2025 22:45:52 -0700 Subject: [PATCH 2/3] docs: fix markup --- .../_draft/sorting_functions.py | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/src/array_api_stubs/_draft/sorting_functions.py b/src/array_api_stubs/_draft/sorting_functions.py index d09f2aa11..6113d5cf4 100644 --- a/src/array_api_stubs/_draft/sorting_functions.py +++ b/src/array_api_stubs/_draft/sorting_functions.py @@ -13,23 +13,23 @@ def argsort( Parameters ---------- x: array - input array. *Should* have a real-valued data type. + input array. **Should** have a real-valued data type. axis: int - axis along which to sort. If set to ``-1``, the function *must* sort along the last axis. Default: ``-1``. + 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 *must* sort ``x`` in descending order (by value). If ``False``, the returned indices *must* sort ``x`` in ascending order (by value). Default: ``False``. + sort order. If ``True``, the returned indices **must** sort ``x`` in descending order (by value). If ``False``, the returned indices **must** 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* 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``. + 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** 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. + 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. Notes ----- - - For backward compatibility, conforming implementations *may* support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). + - For backward compatibility, conforming implementations **may** support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). """ @@ -42,21 +42,21 @@ def sort( Parameters ---------- x: array - input array. *Should* have a real-valued data type. + input array. **Should** have a real-valued data type. axis: int - axis along which to sort. If set to ``-1``, the function *must* sort along the last axis. Default: ``-1``. + 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``. + 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* 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``. + 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** 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``. + a sorted array. The returned array **must** have the same data type and shape as ``x``. Notes ----- - - For backward compatibility, conforming implementations *may* support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). + - For backward compatibility, conforming implementations **may** support complex numbers; however, inequality comparison of complex numbers is unspecified and thus implementation-dependent (see :ref:`complex-number-ordering`). """ From 47d5e2efe5b4a26addd827d3ca7e02837513ab5b Mon Sep 17 00:00:00 2001 From: Athan Date: Mon, 12 May 2025 00:24:58 -0700 Subject: [PATCH 3/3] docs: use consistent `axis` description --- src/array_api_stubs/_draft/sorting_functions.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/array_api_stubs/_draft/sorting_functions.py b/src/array_api_stubs/_draft/sorting_functions.py index 6113d5cf4..53ace4110 100644 --- a/src/array_api_stubs/_draft/sorting_functions.py +++ b/src/array_api_stubs/_draft/sorting_functions.py @@ -15,7 +15,7 @@ def argsort( x: array input array. **Should** have a real-valued data type. axis: int - axis along which to sort. If set to ``-1``, the function **must** sort along the last axis. Default: ``-1``. + axis along which to sort. A valid axis **must** be an integer on the interval ``[-N, N)``, where ``N`` is the number of axes in ``x``. If an axis is specified as a negative integer, the function **must** determine the axis along which to perform the operation by counting backward from the last axis (where ``-1`` refers to the last axis). If provided an invalid axis, the function **must** raise an exception. Default: ``-1``. descending: bool sort order. If ``True``, the returned indices **must** sort ``x`` in descending order (by value). If ``False``, the returned indices **must** sort ``x`` in ascending order (by value). Default: ``False``. stable: bool @@ -44,7 +44,7 @@ def sort( x: array input array. **Should** have a real-valued data type. axis: int - axis along which to sort. If set to ``-1``, the function **must** sort along the last axis. Default: ``-1``. + axis along which to sort. A valid axis **must** be an integer on the interval ``[-N, N)``, where ``N`` is the number of axes in ``x``. If an axis is specified as a negative integer, the function **must** determine the axis along which to perform the operation by counting backward from the last axis (where ``-1`` refers to the last axis). If provided an invalid axis, the function **must** raise an exception. 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