From c4d90fe6d903982d7bbd0bfe272c185df39eb4ab Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Tue, 30 Apr 2024 13:23:34 -0600 Subject: [PATCH 1/3] Add a paragraph making it clearer that RFC 2119 is used --- spec/draft/purpose_and_scope.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/spec/draft/purpose_and_scope.md b/spec/draft/purpose_and_scope.md index f375c9512..528ffac42 100644 --- a/spec/draft/purpose_and_scope.md +++ b/spec/draft/purpose_and_scope.md @@ -460,6 +460,8 @@ a dimension whose size is one. **vector**: a one-dimensional array. +In addition to the above terms, the key words "**must**", "**must not**", "**required**", "**shall**", "**shall not**", "**should**", "**should not**", "**recommended**", "**may**", and "**optional**" in this specification are to be interpreted as described in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119). + * * * ## Normative References From 08f12ce3703e449d8de7a7db54d14212b3992816 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Tue, 30 Apr 2024 16:03:41 -0600 Subject: [PATCH 2/3] Use a list-table instead of an rst table --- spec/2023.12/API_specification/data_types.rst | 61 ++++++++++--------- spec/draft/API_specification/data_types.rst | 61 ++++++++++--------- 2 files changed, 64 insertions(+), 58 deletions(-) diff --git a/spec/2023.12/API_specification/data_types.rst b/spec/2023.12/API_specification/data_types.rst index 5987dd322..5f3a97cda 100644 --- a/spec/2023.12/API_specification/data_types.rst +++ b/spec/2023.12/API_specification/data_types.rst @@ -9,35 +9,38 @@ A conforming implementation of the array API standard must provide and support the following data types ("dtypes") in its array object, and as data type objects in its main namespace under the specified names: -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| dtype object | description | -+==============+============================================================================================================================================================================================+ -| bool | Boolean (``True`` or ``False``). | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| int8 | An 8-bit signed integer whose values exist on the interval ``[-128, +127]``. | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| int16 | A 16-bit signed integer whose values exist on the interval ``[−32,767, +32,767]``. | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| int32 | A 32-bit signed integer whose values exist on the interval ``[−2,147,483,647, +2,147,483,647]``. | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| int64 | A 64-bit signed integer whose values exist on the interval ``[−9,223,372,036,854,775,807, +9,223,372,036,854,775,807]``. | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| uint8 | An 8-bit unsigned integer whose values exist on the interval ``[0, +255]``. | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| uint16 | A 16-bit unsigned integer whose values exist on the interval ``[0, +65,535]``. | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| uint32 | A 32-bit unsigned integer whose values exist on the interval ``[0, +4,294,967,295]``. | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| uint64 | A 64-bit unsigned integer whose values exist on the interval ``[0, +18,446,744,073,709,551,615]``. | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| float32 | IEEE 754 single-precision (32-bit) binary floating-point number (see IEEE 754-2019). | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| float64 | IEEE 754 double-precision (64-bit) binary floating-point number (see IEEE 754-2019). | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| complex64 | Single-precision (64-bit) complex floating-point number whose real and imaginary components must be IEEE 754 single-precision (32-bit) binary floating-point numbers (see IEEE 754-2019). | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| complex128 | Double-precision (128-bit) complex floating-point number whose real and imaginary components must be IEEE 754 double-precision (64-bit) binary floating-point numbers (see IEEE 754-2019). | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - dtype object + - description + * - bool + - Boolean (``True`` or ``False``). + * - int8 + - An 8-bit signed integer whose values exist on the interval ``[-128, +127]``. + * - int16 + - A 16-bit signed integer whose values exist on the interval ``[−32,767, +32,767]``. + * - int32 + - A 32-bit signed integer whose values exist on the interval ``[−2,147,483,647, +2,147,483,647]``. + * - int64 + - A 64-bit signed integer whose values exist on the interval ``[−9,223,372,036,854,775,807, +9,223,372,036,854,775,807]``. + * - uint8 + - An 8-bit unsigned integer whose values exist on the interval ``[0, +255]``. + * - uint16 + - A 16-bit unsigned integer whose values exist on the interval ``[0, +65,535]``. + * - uint32 + - A 32-bit unsigned integer whose values exist on the interval ``[0, +4,294,967,295]``. + * - uint64 + - A 64-bit unsigned integer whose values exist on the interval ``[0, +18,446,744,073,709,551,615]``. + * - float32 + - IEEE 754 single-precision (32-bit) binary floating-point number (see IEEE 754-2019). + * - float64 + - IEEE 754 double-precision (64-bit) binary floating-point number (see IEEE 754-2019). + * - complex64 + - Single-precision (64-bit) complex floating-point number whose real and imaginary components must be IEEE 754 single-precision (32-bit) binary floating-point numbers (see IEEE 754-2019). + * - complex128 + - Double-precision (128-bit) complex floating-point number whose real and imaginary components must be IEEE 754 double-precision (64-bit) binary floating-point numbers (see IEEE 754-2019). Data type objects must have the following methods (no attributes are required): diff --git a/spec/draft/API_specification/data_types.rst b/spec/draft/API_specification/data_types.rst index 5987dd322..5f3a97cda 100644 --- a/spec/draft/API_specification/data_types.rst +++ b/spec/draft/API_specification/data_types.rst @@ -9,35 +9,38 @@ A conforming implementation of the array API standard must provide and support the following data types ("dtypes") in its array object, and as data type objects in its main namespace under the specified names: -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| dtype object | description | -+==============+============================================================================================================================================================================================+ -| bool | Boolean (``True`` or ``False``). | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| int8 | An 8-bit signed integer whose values exist on the interval ``[-128, +127]``. | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| int16 | A 16-bit signed integer whose values exist on the interval ``[−32,767, +32,767]``. | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| int32 | A 32-bit signed integer whose values exist on the interval ``[−2,147,483,647, +2,147,483,647]``. | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| int64 | A 64-bit signed integer whose values exist on the interval ``[−9,223,372,036,854,775,807, +9,223,372,036,854,775,807]``. | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| uint8 | An 8-bit unsigned integer whose values exist on the interval ``[0, +255]``. | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| uint16 | A 16-bit unsigned integer whose values exist on the interval ``[0, +65,535]``. | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| uint32 | A 32-bit unsigned integer whose values exist on the interval ``[0, +4,294,967,295]``. | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| uint64 | A 64-bit unsigned integer whose values exist on the interval ``[0, +18,446,744,073,709,551,615]``. | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| float32 | IEEE 754 single-precision (32-bit) binary floating-point number (see IEEE 754-2019). | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| float64 | IEEE 754 double-precision (64-bit) binary floating-point number (see IEEE 754-2019). | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| complex64 | Single-precision (64-bit) complex floating-point number whose real and imaginary components must be IEEE 754 single-precision (32-bit) binary floating-point numbers (see IEEE 754-2019). | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| complex128 | Double-precision (128-bit) complex floating-point number whose real and imaginary components must be IEEE 754 double-precision (64-bit) binary floating-point numbers (see IEEE 754-2019). | -+--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - dtype object + - description + * - bool + - Boolean (``True`` or ``False``). + * - int8 + - An 8-bit signed integer whose values exist on the interval ``[-128, +127]``. + * - int16 + - A 16-bit signed integer whose values exist on the interval ``[−32,767, +32,767]``. + * - int32 + - A 32-bit signed integer whose values exist on the interval ``[−2,147,483,647, +2,147,483,647]``. + * - int64 + - A 64-bit signed integer whose values exist on the interval ``[−9,223,372,036,854,775,807, +9,223,372,036,854,775,807]``. + * - uint8 + - An 8-bit unsigned integer whose values exist on the interval ``[0, +255]``. + * - uint16 + - A 16-bit unsigned integer whose values exist on the interval ``[0, +65,535]``. + * - uint32 + - A 32-bit unsigned integer whose values exist on the interval ``[0, +4,294,967,295]``. + * - uint64 + - A 64-bit unsigned integer whose values exist on the interval ``[0, +18,446,744,073,709,551,615]``. + * - float32 + - IEEE 754 single-precision (32-bit) binary floating-point number (see IEEE 754-2019). + * - float64 + - IEEE 754 double-precision (64-bit) binary floating-point number (see IEEE 754-2019). + * - complex64 + - Single-precision (64-bit) complex floating-point number whose real and imaginary components must be IEEE 754 single-precision (32-bit) binary floating-point numbers (see IEEE 754-2019). + * - complex128 + - Double-precision (128-bit) complex floating-point number whose real and imaginary components must be IEEE 754 double-precision (64-bit) binary floating-point numbers (see IEEE 754-2019). Data type objects must have the following methods (no attributes are required): From 0d1999ccc1badaa60b4db8ca4454191de0a51e54 Mon Sep 17 00:00:00 2001 From: Aaron Meurer Date: Tue, 30 Apr 2024 16:04:00 -0600 Subject: [PATCH 3/3] Add a sphinx extension to automatically bold RFC 2119 words --- src/_array_api_conf.py | 1 + src/autobold_rfc2119.py | 30 ++++++++++++++++++++++++++++++ 2 files changed, 31 insertions(+) create mode 100644 src/autobold_rfc2119.py diff --git a/src/_array_api_conf.py b/src/_array_api_conf.py index 08929cc43..d0f76e7c1 100644 --- a/src/_array_api_conf.py +++ b/src/_array_api_conf.py @@ -37,6 +37,7 @@ "sphinx_favicon", "sphinx_markdown_tables", "sphinxcontrib.jquery", + "autobold_rfc2119", ] autosummary_generate = True diff --git a/src/autobold_rfc2119.py b/src/autobold_rfc2119.py new file mode 100644 index 000000000..16b327409 --- /dev/null +++ b/src/autobold_rfc2119.py @@ -0,0 +1,30 @@ +from sphinx.application import Sphinx +import re + +rfc_2119_words = [ + 'must', + 'must not', + 'required', + 'shall', + 'shall not', + 'should', + 'should not', + 'recommended', + 'not recommended', + 'may', + 'optional', +] + +def bold_terms(source): + return re.sub(rf'\b({"|".join(rfc_2119_words)})\b(?!\[)', r'**\1**', source, flags=re.IGNORECASE) + +def bold_terms_source_read(app, docname, source): + source[0] = bold_terms(source[0]) + +def bold_terms_autodoc(app, what, name, obj, options, lines): + for i in range(len(lines)): + lines[i] = bold_terms(lines[i]) + +def setup(app: Sphinx): + app.connect('source-read', bold_terms_source_read) + app.connect('autodoc-process-docstring', bold_terms_autodoc)