array-api icon indicating copy to clipboard operation
array-api copied to clipboard

Refactor the boilerplate text at the top of each API spec section

Open rgommers opened this issue 4 years ago • 0 comments

Following up on review comments at https://github.com/data-apis/array-api/pull/189#discussion_r669299943: there's this bit of boilerplate that is repeated over and over in each API docs section. We should put that in a single place, and refer to it in a concise as possible way:

-   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.
-   Broadcasting semantics must follow the semantics defined in {ref}`broadcasting`.
-   Unless stated otherwise, functions must support the data types defined in {ref}`data-types`.
-   Unless stated otherwise, functions must adhere to the type promotion rules defined in {ref}`type-promotion`.
-   Unless stated otherwise, floating-point operations must adhere to IEEE 754-2019.

There's already https://data-apis.org/array-api/latest/API_specification/function_and_method_signatures.html which looks like the right place to add it to.

rgommers avatar Jul 14 '21 07:07 rgommers