Clean up stale documentation and references

doc/docstring_template.py

@@ -28,80 +28,75 @@
 # *****************************************************************************
 
 """
-This is template that should be used when writing docstrings in the project.
-
-According to this template docstrings should consist of below sections:
-1. Short description.
-2. Link to related functionality in `numpy` for full documentation.
-3. Limitations is a special section that should describe:
-   - the limited functionality relative to `numpy` (exception raised)
-   - cases when the functionality will be executed sequentially on CPU
-     (fallback to `numpy`)
-   - list of supported data types for input array
-4. See Also
-5. Notes, optional
-6. Examples
-
-Recommendations:
-1. Short description
-   maybe partially taken/combined from `numpy` and `cupy` docstrings.
-2. Limitations basically should be described according to the code,
-   paying attention to raised exceptions and fallback to `numpy`.
-3. See Also may include links to similar functionality in `dpnp`
-   with short description.
-
-   In case of only one link better to use one-line section:
-   .. seealso:: :func:`numpy.func` short description.
-
-4. Examples maybe partially taken from `numpy` docstrings
-   with some modifications, ex:
-
-   >>> import dpnp as np
-   >>> a = np.array([0, 1, 2])
-   >>> a  # prints unclear result <DPNP DParray:...
-
-   So the array may be printed through iterating:
-
-   >>> [i for i in a]
-   [0, 1, 2]
-
-`dpnp.array` contains a good example of docstring.
+Template for docstrings of dpnp functions.
+
+Docstrings use the numpydoc format and are rendered by ``doc/conf.py``. They
+consist of the sections below, in this order; skip the ones that don't apply:
+
+1. Short (one-line) description.
+2. Link to the reference function: ``For full documentation refer to
+   :obj:`numpy.func`.`` (or ``:obj:`scipy...``` for ``dpnp.scipy``).
+3. Parameters. Array inputs are typed ``{dpnp.ndarray, usm_ndarray}``. Every
+   keyword with a default ends with a blank line and ``Default: ``value``.``.
+4. Returns, typically ``out : dpnp.ndarray``.
+5. Raises, Warns, Warnings.
+6. Limitations: what is not supported compared to the reference function and
+   the exception raised for it, usually ``NotImplementedError``.
+7. See Also: related dpnp functions, each with a short description.
+8. Notes, References.
+9. Examples, starting with ``>>> import dpnp as np``.
+
+Use an existing function, e.g. :obj:`dpnp.cbrt`, as a model, and copy the
+`device`, `usm_type` and `sycl_queue` parameter descriptions from an array
+creation function such as :obj:`dpnp.empty`.
 
 """
 
 
-def func(a, b=None, c=True):
+def func(a, /, out=None, *, order="K", where=True):
     """
     Short (one-line) description.
 
     For full documentation refer to :obj:`numpy.func`.
 
+    Parameters
+    ----------
+    a : {dpnp.ndarray, usm_ndarray}
+        Input array.
+    out : {None, dpnp.ndarray, usm_ndarray}, optional
+        Output array to populate. Array must have the correct shape and the
+        expected data type.
+
+        Default: ``None``.
+    order : {None, "C", "F", "A", "K"}, optional
+        Memory layout of the newly output array, if parameter `out` is
+        ``None``.
+
+        Default: ``"K"``.
+
+    Returns
+    -------
+    out : dpnp.ndarray
+        An array containing the result.
+
     Limitations
     -----------
-    Some limitations in comparison to baseline, ex:
-    Input array data types are limited by supported DPNP :ref:`Data types`.
-    Parameter `c` is supported only with default value ``True``.
-    Otherwise the function will be executed sequentially on CPU.
+    Parameter `where` is supported only with default value ``True``.
+    Otherwise ``NotImplementedError`` exception will be raised.
 
     See Also
     --------
-    :obj:`dpnp.func2` : Short (one-line) description of the function `dpnp.func2`.
-    :obj:`dpnp.func3` : Short (one-line) description of the function `dpnp.func3`.
+    :obj:`dpnp.func2` : Short (one-line) description of `dpnp.func2`.
 
     Notes
     -----
-    Some notes if required.
+    Some notes, if needed.
 
     Examples
     --------
-    Some examples, ex:
-
     >>> import dpnp as np
     >>> a = np.array([0, 1, 2])
-    >>> b = np.array([2, 1, 0])
-    >>> x = np.func(a, b=b, c=True)
-    >>> [i for i in x]
-    [2, 2, 2]
+    >>> np.func(a)
+    array([0, 1, 2])
 
     """
-    pass

doc/quick_start_guide.rst

@@ -113,16 +113,16 @@ To build and install the package on Linux OS, run:
 .. code-block:: bash
 
     python setup.py build_ext --inplace -- -G Ninja -DCMAKE_C_COMPILER:PATH=icx -DCMAKE_CXX_COMPILER:PATH=icpx
-    python -m pip install -e .
+    python -m pip install -e . --no-build-isolation
 
 To build and install the package on Windows OS, run:
 
 .. code-block:: bash
 
     python setup.py build_ext --inplace -- -G Ninja -DCMAKE_C_COMPILER:PATH=icx -DCMAKE_CXX_COMPILER:PATH=icx
-    python -m pip install -e .
+    python -m pip install -e . --no-build-isolation
 
-Alternatively, to develop on Linux OS, you can use the driver script:
+Alternatively, to develop on Linux or Windows OS, you can use the driver script:
 
 .. code-block:: bash
 
@@ -200,6 +200,7 @@ You can then use one of them as the argument to ``--target-hip``.
 For example:
 
 .. code-block:: bash
+
     python scripts/build_locally.py --target-hip=gfx90a
 
 Multi-target build
@@ -235,12 +236,18 @@ These options are useful when building pybind11 extensions that use
 Testing
 =======
 
-If you want to execute the scope of Python test suites which are available
-by the source, you will need to run a command as below:
+To run the test suite from the source tree, after building the package as
+described above, run:
+
+.. code-block:: bash
+
+    python -m pytest dpnp/tests
+
+To run the tests of an installed ``dpnp`` package, run:
 
 .. code-block:: bash
 
-    pytest -s tests
+    python -m pytest --pyargs dpnp.tests
 
 Examples
 ========

doc/reference/index.rst

@@ -16,21 +16,7 @@ API reference of the Data Parallel Extension for NumPy*
    ndarray
    ufunc
    routines
-   special
    scipy
-   sparse
-   ndimage
-   generic
-   memory
-   cuda
-   memoize
-   kernel
-   optimize
-   interoperability
-   testing
-   prof
-   environment
    dtypes_table
    comparison
-   misc
    array_api

doc/reference/polynomials.rst

@@ -1,3 +1,7 @@
+:orphan:
+
+.. Not in any toctree until dpnp implements the polynomial routines.
+
 .. currentmodule:: dpnp
 
 Polynomials

dpnp/tensor/_array_api.py

@@ -143,12 +143,12 @@ def default_dtypes(self, *, device=None):
         Returns a dictionary of default data types for ``device``.
 
         Args:
-            device (Optional[:class:`dpctl.SyclDevice`, :class:`dpctl.SyclQueue`, :class:`dpctl.tensor.Device`, str]):
+            device (Optional[:class:`dpctl.SyclDevice`, :class:`dpctl.SyclQueue`, :class:`dpnp.tensor.Device`, str]):
                 array API concept of device used in getting default data types.
                 ``device`` can be ``None`` (in which case the default device
                 is used), an instance of :class:`dpctl.SyclDevice`, an instance
-                of :class:`dpctl.SyclQueue`, a :class:`dpctl.tensor.Device`
-                object returned by :attr:`dpctl.tensor.usm_ndarray.device`, or
+                of :class:`dpctl.SyclQueue`, a :class:`dpnp.tensor.Device`
+                object returned by :attr:`dpnp.tensor.usm_ndarray.device`, or
                 a filter selector string.
                 Default: ``None``.
 
@@ -181,12 +181,12 @@ def dtypes(self, *, device=None, kind=None):
         specification.
 
         Args:
-            device (Optional[:class:`dpctl.SyclDevice`, :class:`dpctl.SyclQueue`, :class:`dpctl.tensor.Device`, str]):
+            device (Optional[:class:`dpctl.SyclDevice`, :class:`dpctl.SyclQueue`, :class:`dpnp.tensor.Device`, str]):
                 array API concept of device used in getting default data types.
                 ``device`` can be ``None`` (in which case the default device is
                 used), an instance of :class:`dpctl.SyclDevice`, an instance of
-                :class:`dpctl.SyclQueue`, a :class:`dpctl.tensor.Device`
-                object returned by :attr:`dpctl.tensor.usm_ndarray.device`, or
+                :class:`dpctl.SyclQueue`, a :class:`dpnp.tensor.Device`
+                object returned by :attr:`dpnp.tensor.usm_ndarray.device`, or
                 a filter selector string.
                 Default: ``None``.
 

dpnp/tensor/_compute_follows_data.pyx

@@ -53,7 +53,7 @@ class ExecutionPlacementError(Exception):
     Make sure that input arrays are associated with the same
     :class:`dpctl.SyclQueue`,
     or migrate data to the same :class:`dpctl.SyclQueue` using
-    :meth:`dpctl.tensor.usm_ndarray.to_device` method.
+    :meth:`dpnp.tensor.usm_ndarray.to_device` method.
     """
     pass
 

dpnp/tensor/_copy_utils.py

@@ -45,7 +45,7 @@
 
 __doc__ = (
     "Implementation module for copy- and cast- operations on "
-    ":class:`dpctl.tensor.usm_ndarray`."
+    ":class:`dpnp.tensor.usm_ndarray`."
 )
 
 int32_t_max = 1 + np.iinfo(np.int32).max
@@ -102,7 +102,7 @@ def _copy_from_numpy(np_ary, usm_type="device", sycl_queue=None):
 
 
 def _copy_from_numpy_into(dst, np_ary):
-    """Copies `np_ary` into `dst` of type :class:`dpctl.tensor.usm_ndarray"""
+    """Copies `np_ary` into `dst` of type :class:`dpnp.tensor.usm_ndarray"""
     if not isinstance(np_ary, np.ndarray):
         raise TypeError(f"Expected numpy.ndarray, got {type(np_ary)}")
     if not isinstance(dst, dpt.usm_ndarray):
@@ -547,7 +547,7 @@ def from_numpy(np_ary, /, *, device=None, usm_type="device", sycl_queue=None):
     """
     from_numpy(arg, device=None, usm_type="device", sycl_queue=None)
 
-    Creates :class:`dpctl.tensor.usm_ndarray` from instance of
+    Creates :class:`dpnp.tensor.usm_ndarray` from instance of
     :class:`numpy.ndarray`.
 
     Args:
@@ -558,7 +558,7 @@ def from_numpy(np_ary, /, *, device=None, usm_type="device", sycl_queue=None):
             a filter selector string, an instance of
             :class:`dpctl.SyclDevice`, an instance of
             :class:`dpctl.SyclQueue`, or an instance of
-            :class:`dpctl.tensor.Device`. If the value is ``None``,
+            :class:`dpnp.tensor.Device`. If the value is ``None``,
             returned array is created on the default-selected device.
             Default: ``None``
         usm_type (str): The requested USM allocation type for the
@@ -586,7 +586,7 @@ def to_numpy(usm_ary, /):
     """
     to_numpy(usm_ary)
 
-    Copies content of :class:`dpctl.tensor.usm_ndarray` instance ``usm_ary``
+    Copies content of :class:`dpnp.tensor.usm_ndarray` instance ``usm_ary``
     into :class:`numpy.ndarray` instance of the same shape and same data type.
 
     Args:
@@ -604,7 +604,7 @@ def asnumpy(usm_ary, order="K"):
     """
     asnumpy(usm_ary, order="K")
 
-    Copies content of :class:`dpctl.tensor.usm_ndarray` instance ``usm_ary``
+    Copies content of :class:`dpnp.tensor.usm_ndarray` instance ``usm_ary``
     into :class:`numpy.ndarray` instance of the same shape and same data
     type.
 
@@ -988,7 +988,7 @@ def _empty_like_triple_orderK(X1, X2, X3, dt, res_shape, usm_type, dev):
 def copy(usm_ary, /, *, order="K"):
     """copy(ary, order="K")
 
-    Creates a copy of given instance of :class:`dpctl.tensor.usm_ndarray`.
+    Creates a copy of given instance of :class:`dpnp.tensor.usm_ndarray`.
 
     Args:
         ary (usm_ndarray):
@@ -1061,7 +1061,7 @@ def astype(
     """astype(array, new_dtype, order="K", casting="unsafe", \
             copy=True, device=None)
 
-    Returns a copy of the :class:`dpctl.tensor.usm_ndarray`, cast to a
+    Returns a copy of the :class:`dpnp.tensor.usm_ndarray`, cast to a
     specified type.
 
     Args:
@@ -1086,7 +1086,7 @@ def astype(
             a filter selector string, an instance of
             :class:`dpctl.SyclDevice`, an instance of
             :class:`dpctl.SyclQueue`, or an instance of
-            :class:`dpctl.tensor.Device`. If the value is `None`,
+            :class:`dpnp.tensor.Device`. If the value is `None`,
             returned array is created on the same device as `array`.
             Default: `None`.