Return named tuple for linalg functions per python array API (#2276)

The PR proposes to return namedtuple for linalg functions: `qr`, `eig`,
`eigh`, `svd` and `slogdet`.
The namedtuple as a return type there is mandated to be compliant with
python array API.

The tests are updated to cover namedtyple as a return type of affected
function.
Also this PR requires to patch how napoleon extension from sphinx
handles docstring description of namedtuple. The handling was align with
NumPy approach.

Author: antonwolfy

.github/workflows/array-api-skips.txt

@@ -17,13 +17,7 @@ array_api_tests/test_signatures.py::test_func_signature[unique_counts]
 array_api_tests/test_signatures.py::test_func_signature[unique_inverse]
 array_api_tests/test_signatures.py::test_func_signature[unique_values]
 
-# do not return a namedtuple
-array_api_tests/test_linalg.py::test_eigh
-array_api_tests/test_linalg.py::test_slogdet
-array_api_tests/test_linalg.py::test_svd
-
 # hypothesis found failures
-array_api_tests/test_linalg.py::test_qr
 array_api_tests/test_operators_and_elementwise_functions.py::test_clip
 
 # unexpected result is returned - unmute when dpctl-1986 is resolved

doc/conf.py

@@ -9,6 +9,7 @@
 from datetime import datetime
 
 from sphinx.ext.autodoc import FunctionDocumenter
+from sphinx.ext.napoleon import NumpyDocstring, docstring
 
 from dpnp.dpnp_algo.dpnp_elementwise_common import DPNPBinaryFunc, DPNPUnaryFunc
 
@@ -231,3 +232,59 @@ def _can_document_member(member, *args, **kwargs):
 napoleon_use_ivar = True
 napoleon_include_special_with_doc = True
 napoleon_custom_sections = ["limitations"]
+
+
+# Napoleon extension can't properly render "Returns" section in case of
+# namedtuple as a return type. That patch proposes to extend the parse logic
+# which allows text in a header of "Returns" section.
+def _parse_returns_section_patched(self, section: str) -> list[str]:
+    fields = self._consume_returns_section()
+    multi = len(fields) > 1
+    use_rtype = False if multi else self._config.napoleon_use_rtype
+    lines: list[str] = []
+    header: list[str] = []
+    is_logged_header = False
+
+    for _name, _type, _desc in fields:
+        # self._consume_returns_section() stores the header block
+        # into `_type` argument, while `_name` has to be empty string and
+        # `_desc` has to be empty list of strings
+        if _name == "" and (not _desc or len(_desc) == 1 and _desc[0] == ""):
+            if not is_logged_header:
+                docstring.logger.info(
+                    "parse a header block of 'Returns' section",
+                    location=self._get_location(),
+                )
+                is_logged_header = True
+
+            # build a list with lines of the header block
+            header.extend([_type])
+            continue
+
+        if use_rtype:
+            field = self._format_field(_name, "", _desc)
+        else:
+            field = self._format_field(_name, _type, _desc)
+
+        if multi:
+            if lines:
+                lines.extend(self._format_block("          * ", field))
+            else:
+                if header:
+                    # add the header block + the 1st parameter stored in `field`
+                    lines.extend([":returns:", ""])
+                    lines.extend(self._format_block(" " * 4, header))
+                    lines.extend(self._format_block("          * ", field))
+                else:
+                    lines.extend(self._format_block(":returns: * ", field))
+        else:
+            if any(field):  # only add :returns: if there's something to say
+                lines.extend(self._format_block(":returns: ", field))
+            if _type and use_rtype:
+                lines.extend([f":rtype: {_type}", ""])
+    if lines and lines[-1]:
+        lines.append("")
+    return lines
+
+
+NumpyDocstring._parse_returns_section = _parse_returns_section_patched

dpnp/dpnp_array.py

@@ -760,12 +760,14 @@ def argsort(
 
     def asnumpy(self):
         """
-        Copy content of the array into :class:`numpy.ndarray` instance of the same shape and data type.
+        Copy content of the array into :class:`numpy.ndarray` instance of
+        the same shape and data type.
 
         Returns
         -------
-        numpy.ndarray
-            An instance of :class:`numpy.ndarray` populated with the array content.
+        out : numpy.ndarray
+            An instance of :class:`numpy.ndarray` populated with the array
+            content.
 
         """
 

dpnp/dpnp_iface_manipulation.py

@@ -1124,7 +1124,7 @@ def broadcast_shapes(*args):
 
     Returns
     -------
-    tuple
+    out : tuple
         Broadcasted shape.
 
     See Also

dpnp/dpnp_iface_statistics.py

@@ -843,7 +843,7 @@ def max(a, axis=None, out=None, keepdims=False, initial=None, where=True):
         dimension ``a.ndim - len(axis)``.
 
     Limitations
-    -----------.
+    -----------
     Parameters `where`, and `initial` are only supported with their default
     values. Otherwise ``NotImplementedError`` exception will be raised.