diff --git a/spec/API_specification/function_and_method_signatures.md b/spec/API_specification/function_and_method_signatures.rst
similarity index 52%
rename from spec/API_specification/function_and_method_signatures.md
rename to spec/API_specification/function_and_method_signatures.rst
index d199bcbb6..86d0819a6 100644
--- a/spec/API_specification/function_and_method_signatures.md
+++ b/spec/API_specification/function_and_method_signatures.rst
@@ -1,36 +1,34 @@
-(function-and-method-signatures)=
+.. _function-and-method-signatures:
-# Function and method signatures
+Function and method signatures
+==============================
Function signatures in this standard adhere to the following:
-1. Positional parameters must be
- [positional-only](https://www.python.org/dev/peps/pep-0570/) parameters.
+1. Positional parameters must be `positional-only `_ 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.
- _Rationale: existing libraries have incompatible conventions, and using names
- of positional parameters is not normal/recommended practice._
+ *Rationale: existing libraries have incompatible conventions, and using names
+ of positional parameters is not normal/recommended practice.*
- ```{note}
+ .. note::
Positional-only parameters are only available in Python >= 3.8. Libraries
still supporting 3.7 or 3.6 may consider making the API standard-compliant
namespace >= 3.8. Alternatively, they can add guidance to their users in the
- documentation to use the functions as if they were positional-only.
- ```
+ documentation to use the functions as if they were positional-only.
-2. Optional parameters must be
- [keyword-only](https://www.python.org/dev/peps/pep-3102/) arguments.
+2. Optional parameters must be `keyword-only `_ arguments.
- _Rationale: this leads to more readable code, and it makes it easier to
+ *Rationale: this leads to more readable code, and it makes it easier to
evolve an API over time by adding keywords without having to worry about
- keyword order._
+ keyword order.*
3. For functions that have a single positional array parameter, that parameter
- is called `x`. For functions that have multiple array parameters, those
- parameters are called `xi` with `i = 1, 2, ...` (i.e., `x1`, `x2`).
+ is called ``x``. For functions that have multiple array parameters, those
+ parameters are called ``xi`` with ``i = 1, 2, ...`` (i.e., ``x1``, ``x2``).
4. Type annotations are left out of the signatures themselves for readability; however,
they are added to individual parameter descriptions. For code which aims to
@@ -38,25 +36,24 @@ Function signatures in this standard adhere to the following:
A function signature and description will look like:
-```
-funcname(x1, x2, /, *, key1=-1, key2=None)
+::
- Parameters
+ funcname(x1, x2, /, *, key1=-1, key2=None) -> out:
+ Parameters
- x1 : array
- description
- x2 : array
- description
- key1 : int
- description
- key2 : Optional[str]
- description
+ x1 : array
+ description
+ x2 : array
+ description
+ key1 : int
+ description
+ key2 : Optional[str]
+ description
- Returns
+ Returns
- out : array
- description
-```
+ out : array
+ description
-Method signatures will follow the same conventions modulo the addition of
-`self`.
+
+Method signatures will follow the same conventions modulo the addition of ``self``.