Update dpnp.ndarray docstrings (#2422)

This PR improves documentations of `dpnp.ndarray` class, including:
- adding missing docstrings to the methods and attributes
- extending `ndarray.rst` page to have all methods and attributes
rendered
- aligning signatures of the methods with numpy.ndarray class
- adding a page with dpnp constants
- updating a link with `dpnp.DLDeviceType` enum

Also `dpnp_array.py` was added to pylint scope.

Author: antonwolfy

.pre-commit-config.yaml

@@ -119,7 +119,7 @@ repos:
             "--disable=redefined-builtin",
             "--disable=unused-wildcard-import"
             ]
-        files: '^dpnp/(dpnp_iface.*|fft|linalg)'
+        files: '^dpnp/(dpnp_iface.*|fft|linalg|dpnp_array)'
 -   repo: https://github.com/macisamuele/language-formatters-pre-commit-hooks
     rev: v2.14.0
     hooks:

CHANGELOG.md

@@ -29,6 +29,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Removed the use of class template argument deduction for alias template to conform to the C++17 standard [#2517](https://github.com/IntelPython/dpnp/pull/2517)
 * Changed th order of individual FFTs over `axes` for `dpnp.fft.irfftn` to be in forward order [#2524](https://github.com/IntelPython/dpnp/pull/2524)
 * Replaced the use of `numpy.testing.suppress_warnings` with appropriate calls from the warnings module [#2529](https://github.com/IntelPython/dpnp/pull/2529)
+* Improved documentations of `dpnp.ndarray` class and added a page with description of supported constants [#2422](https://github.com/IntelPython/dpnp/pull/2422)
 
 ### Deprecated
 

doc/reference/constants.rst

@@ -0,0 +1,162 @@
+Constants
+=========
+
+DPNP includes several constants:
+
+.. currentmodule:: dpnp
+
+.. autodata:: DLDeviceType
+
+.. data:: e
+
+    Euler's constant, base of natural logarithms, Napier's constant.
+
+    ``e = 2.71828182845904523536028747135266249775724709369995...``
+
+    .. rubric:: See Also
+
+    :func:`exp` : Exponential function
+
+    :func:`log` : Natural logarithm
+
+    .. rubric:: References
+
+    https://en.wikipedia.org/wiki/E_%28mathematical_constant%29
+
+
+.. data:: euler_gamma
+
+    ``γ = 0.5772156649015328606065120900824024310421...``
+
+    .. rubric:: References
+
+    https://en.wikipedia.org/wiki/Euler%27s_constant
+
+
+.. data:: inf
+
+    IEEE 754 floating point representation of (positive) infinity.
+
+    .. rubric:: Returns
+
+    y : float
+        A floating point representation of positive infinity.
+
+    .. rubric:: See Also
+
+    :func:`isinf` : Shows which elements are positive or negative infinity
+
+    :func:`isposinf` : Shows which elements are positive infinity
+
+    :func:`isneginf` : Shows which elements are negative infinity
+
+    :func:`isnan` : Shows which elements are Not a Number
+
+    :func:`isfinite` : Shows which elements are finite (not one of Not a Number,
+    positive infinity and negative infinity)
+
+    .. rubric:: Notes
+
+    DPNP uses the IEEE Standard for Binary Floating-Point for Arithmetic
+    (IEEE 754). This means that Not a Number is not equivalent to infinity.
+    Also that positive infinity is not equivalent to negative infinity. But
+    infinity is equivalent to positive infinity.
+
+    .. rubric:: Examples
+
+    .. code-block:: python
+
+        >>> import dpnp as np
+        >>> np.inf
+        inf
+        >>> np.array([1]) / 0.0
+        array([inf])
+
+
+.. data:: nan
+
+    IEEE 754 floating point representation of Not a Number (NaN).
+
+    .. rubric:: Returns
+
+    y : A floating point representation of Not a Number.
+
+    .. rubric:: See Also
+
+    :func:`isnan` : Shows which elements are Not a Number
+
+    :func:`isfinite` : Shows which elements are finite (not one of Not a Number,
+    positive infinity and negative infinity)
+
+    .. rubric:: Notes
+
+    DPNP uses the IEEE Standard for Binary Floating-Point for Arithmetic
+    (IEEE 754). This means that Not a Number is not equivalent to infinity.
+
+    .. rubric:: Examples
+
+    .. code-block:: python
+
+        >>> import dpnp as np
+        >>> np.nan
+        nan
+        >>> np.log(np.array(-1))
+        array(nan)
+        >>> np.log(np.array([-1, 1, 2]))
+        array([       nan, 0.        , 0.69314718])
+
+
+.. data:: newaxis
+
+    A convenient alias for *None*, useful for indexing arrays.
+
+    .. rubric:: Examples
+
+    .. code-block:: python
+
+        >>> import dpnp as np
+        >>> np.newaxis is None
+        True
+        >>> x = np.arange(3)
+        >>> x
+        array([0, 1, 2])
+        >>> x[:, np.newaxis]
+        array([[0],
+               [1],
+               [2]])
+        >>> x[:, np.newaxis, np.newaxis]
+        array([[[0]],
+               [[1]],
+               [[2]]])
+        >>> x[:, np.newaxis] * x
+        array([[0, 0, 0],
+               [0, 1, 2],
+               [0, 2, 4]])
+
+        Outer product, same as ``outer(x, y)``:
+
+        >>> y = np.arange(3, 6)
+        >>> x[:, np.newaxis] * y
+        array([[ 0,  0,  0],
+            [ 3,  4,  5],
+            [ 6,  8, 10]])
+
+        ``x[np.newaxis, :]`` is equivalent to ``x[np.newaxis]`` and ``x[None]``:
+
+        >>> x[np.newaxis, :].shape
+        (1, 3)
+        >>> x[np.newaxis].shape
+        (1, 3)
+        >>> x[None].shape
+        (1, 3)
+        >>> x[:, np.newaxis].shape
+        (3, 1)
+
+
+.. data:: pi
+
+    ``pi = 3.1415926535897932384626433...``
+
+    .. rubric:: References
+
+    https://en.wikipedia.org/wiki/Pi

doc/reference/ndarray.rst

@@ -66,7 +66,11 @@ of the array:
    dpnp.ndarray.size
    dpnp.ndarray.itemsize
    dpnp.ndarray.nbytes
-   dpnp.ndarray.base
+   dpnp.ndarray.device
+   dpnp.ndarray.sycl_context
+   dpnp.ndarray.sycl_device
+   dpnp.ndarray.sycl_queue
+   dpnp.ndarray.usm_type
 
 
 Data type
@@ -98,6 +102,17 @@ Other attributes
    dpnp.ndarray.flat
 
 
+Special attributes
+------------------
+
+.. autosummary::
+   :toctree: generated/
+   :nosignatures:
+
+   dpnp.ndarray.__sycl_usm_array_interface__
+   dpnp.ndarray.__usm_ndarray__
+
+
 Array methods
 -------------
 
@@ -145,6 +160,7 @@ Array conversion
    dpnp.ndarray.getfield
    dpnp.ndarray.setflags
    dpnp.ndarray.fill
+   dpnp.ndarray.get_array
 
 
 Shape manipulation
@@ -195,6 +211,26 @@ the operation should proceed.
 Calculation
 -----------
 
+Many of these methods take an argument named *axis*. In such cases,
+
+- If *axis* is *None* (the default), the array is treated as a 1-D array and
+  the operation is performed over the entire array. This behavior is also the
+  default if *self* is a 0-dimensional array.
+
+- If *axis* is an integer, then the operation is done over the given axis (for
+  each 1-D subarray that can be created along the given axis).
+
+The parameter *dtype* specifies the data type over which a reduction operation
+(like summing) should take place. The default reduce data type is the same as
+the data type of *self*. To avoid overflow, it can be useful to perform the
+reduction using a larger data type.
+
+For several methods, an optional *out* argument can also be provided and the
+result will be placed into the output array given. The *out* argument must be
+an :class:`dpnp.ndarray` and have the same number of elements as the result
+array. It can have a different data type in which case casting will be
+performed.
+
 .. autosummary::
    :toctree: generated/
    :nosignatures:
@@ -226,12 +262,11 @@ Arithmetic and comparison operations on :class:`dpnp.ndarrays <dpnp.ndarray>`
 are defined as element-wise operations, and generally yield
 :class:`dpnp.ndarray` objects as results.
 
-Each of the arithmetic operations (``+``, ``-``, ``*``, ``/``, ``//``,
-``%``, ``divmod()``, ``**`` or ``pow()``, ``<<``, ``>>``, ``&``,
-``^``, ``|``, ``~``) and the comparisons (``==``, ``<``, ``>``,
-``<=``, ``>=``, ``!=``) is equivalent to the corresponding
-universal function (or :term:`ufunc` for short) in DPNP. For
-more information, see the section on :ref:`Universal Functions
+Each of the arithmetic operations (``+``, ``-``, ``*``, ``/``, ``//``, ``%``,
+``divmod()``, ``**`` or ``pow()``, ``<<``, ``>>``, ``&``, ``^``, ``|``, ``~``)
+and the comparisons (``==``, ``<``, ``>``, ``<=``, ``>=``, ``!=``) is
+equivalent to the corresponding universal function (or :term:`ufunc` for short)
+in DPNP. For more information, see the section on :ref:`Universal Functions
 <ufuncs>`.
 
 
@@ -252,6 +287,7 @@ Truth value of an array (:class:`bool() <bool>`):
 
 .. autosummary::
    :toctree: generated/
+   :nosignatures:
 
    dpnp.ndarray.__bool__
 
@@ -343,6 +379,7 @@ Matrix Multiplication:
 
 .. autosummary::
    :toctree: generated/
+   :nosignatures:
 
    dpnp.ndarray.__matmul__
    dpnp.ndarray.__rmatmul__
@@ -371,7 +408,10 @@ Basic customization:
 
    dpnp.ndarray.__new__
    dpnp.ndarray.__array__
+   dpnp.ndarray.__array_namespace__
    dpnp.ndarray.__array_wrap__
+   dpnp.ndarray.__dlpack__
+   dpnp.ndarray.__dlpack_device__
 
 Container customization: (see :ref:`Indexing <routines.indexing>`)
 
@@ -380,19 +420,21 @@ Container customization: (see :ref:`Indexing <routines.indexing>`)
    :nosignatures:
 
    dpnp.ndarray.__len__
+   dpnp.ndarray.__iter__
    dpnp.ndarray.__getitem__
    dpnp.ndarray.__setitem__
    dpnp.ndarray.__contains__
 
-Conversion; the operations :class:`int() <int>`,
-:class:`float() <float>` and :class:`complex() <complex>`.
+Conversion; the operations :class:`int() <int>`, :class:`float() <float>`,
+:class:`complex() <complex>` and :func:`operator.index() <operator.index>`.
 They work only on arrays that have one element in them
 and return the appropriate scalar.
 
 .. autosummary::
    :toctree: generated/
    :nosignatures:
 
+   dpnp.ndarray.__index__
    dpnp.ndarray.__int__
    dpnp.ndarray.__float__
    dpnp.ndarray.__complex__

doc/reference/routines.rst

@@ -11,6 +11,7 @@ These functions cover a subset of
 .. toctree::
    :maxdepth: 2
 
+   constants
    array-creation
    array-manipulation
    bitwise