Merge pull request IntelPython#1626 from IntelPython/docstring-edits-…

…only

Docstring edits only changes in documentation overhaul

dpctl/_sycl_context.pyx

@@ -60,9 +60,8 @@ _logger = logging.getLogger(__name__)
 
 cdef class SyclContextCreationError(Exception):
     """
-    A SyclContextCreationError exception is raised when
-    SyclContext could not created.
-
+    A ``SyclContextCreationError`` exception is raised
+    when :class:`.SyclContext` could not created.
     """
     pass
 
@@ -97,7 +96,7 @@ cdef class _SyclContext:
 cdef class SyclContext(_SyclContext):
     """
     SyclContext(arg=None)
-    A Python wrapper for the :sycl_context:`sycl::context <>` C++ class.
+    A Python wrapper for the ``sycl::context`` C++ class.
 
     There are multiple ways to create a :class:`dpctl.SyclContext` object:
 
@@ -109,7 +108,7 @@ cdef class SyclContext(_SyclContext):
 
                 import dpctl
 
-                # Create a default SyclContext
+                # Create a SyclContext for default-selected device
                 ctx = dpctl.SyclContext()
                 print(ctx.get_devices())
 

dpctl/_sycl_device.pyx

@@ -122,25 +122,26 @@ __all__ = [
 
 cdef class SyclDeviceCreationError(Exception):
     """
-    A SyclDeviceCreationError exception is raised when
-    SyclDevice instance could not created.
-
+    A ``SyclDeviceCreationError`` exception is raised when
+    :class:`.SyclDevice` instance could not created.
     """
     pass
 
 
 cdef class SyclSubDeviceCreationError(Exception):
     """
-    A SyclSubDeviceCreationError exception is raised when
-    sub-devices were not created.
-
+    A ``SyclSubDeviceCreationError`` exception is raised
+    by :meth:`.SyclDevice.create_sub_devices` when
+    :class:`.SyclDevice` instance could not be partitioned
+    into sub-devices.
     """
     pass
 
 
 cdef class _SyclDevice:
     """
-    A helper data-owner class to abstract a `sycl::device` instance.
+    A helper data-owner class to abstract ``sycl::device``
+    instance.
     """
 
     def __dealloc__(self):
@@ -234,7 +235,7 @@ def _cached_filter_string(d : SyclDevice):
 
 cdef class SyclDevice(_SyclDevice):
     """ SyclDevice(arg=None)
-    A Python wrapper for the :sycl_device:`sycl::device <>` C++ class.
+    A Python wrapper for the ``sycl::device`` C++ class.
 
     There are two ways of creating a SyclDevice instance:
 
@@ -254,10 +255,10 @@ cdef class SyclDevice(_SyclDevice):
 
         - by calling one of the device selector helper functions:
 
-          :func:`dpctl.select_accelerator_device()`,
-          :func:`dpctl.select_cpu_device()`,
-          :func:`dpctl.select_default_device()`,
-          :func:`dpctl.select_gpu_device()`,
+          :py:func:`dpctl.select_accelerator_device()`,
+          :py:func:`dpctl.select_cpu_device()`,
+          :py:func:`dpctl.select_default_device()`,
+          :py:func:`dpctl.select_gpu_device()`,
 
 
         :Example:
@@ -283,7 +284,6 @@ cdef class SyclDevice(_SyclDevice):
                    or the input capsule contained a null pointer or could not
                    be renamed.
 
-
     """
     @staticmethod
     cdef SyclDevice _create(DPCTLSyclDeviceRef dref):

dpctl/_sycl_device_factory.pyx

@@ -141,7 +141,7 @@ cdef list _get_devices(DPCTLDeviceVectorRef DVRef):
 
 
 cpdef list get_devices(backend=backend_type.all, device_type=device_type_t.all):
-    """ get_devices(backend=backend_type.all, device_type=device_type_t.all)
+    """
     Returns a list of :class:`dpctl.SyclDevice` instances selected based on
     the given :class:`dpctl.device_type` and :class:`dpctl.backend_type` values.
 
@@ -150,18 +150,21 @@ cpdef list get_devices(backend=backend_type.all, device_type=device_type_t.all):
     ``backend`` in addition to only ``device_type``.
 
     Args:
-        backend (optional): Defaults to ``dpctl.backend_type.all``.
+        backend (optional):
             A :class:`dpctl.backend_type` enum value or a string that
             specifies a SYCL backend. Currently, accepted values are: "cuda",
             "opencl", "level_zero", or "all".
-        device_type (optional): Defaults to ``dpctl.device_type.all``.
+            Default: ``dpctl.backend_type.all``.
+        device_type (optional):
             A :class:`dpctl.device_type` enum value or a string that
             specifies a SYCL device type. Currently, accepted values are:
             "gpu", "cpu", "accelerator", "host", or "all".
+            Default: ``dpctl.device_type.all``.
     Returns:
-        list: A list of available :class:`dpctl.SyclDevice` instances that
-        satisfy the provided :class:`dpctl.backend_type` and
-        :class:`dpctl.device_type` values.
+        list:
+            A list of available :class:`dpctl.SyclDevice` instances that
+            satisfy the provided :class:`dpctl.backend_type` and
+            :class:`dpctl.device_type` values.
     """
     cdef _backend_type BTy = _backend_type._ALL_BACKENDS
     cdef _device_type DTy = _device_type._ALL_DEVICES
@@ -198,22 +201,26 @@ cpdef list get_devices(backend=backend_type.all, device_type=device_type_t.all):
 cpdef int get_num_devices(
     backend=backend_type.all, device_type=device_type_t.all
 ):
-    """ get_num_devices(backend=backend_type.all, device_type=device_type_t.all)
+    """
     A helper function to return the number of SYCL devices of a given
     :class:`dpctl.device_type` and :class:`dpctl.backend_type`.
 
     Args:
-        backend (optional): Defaults to ``dpctl.backend_type.all``.
+        backend (optional):
             A :class:`dpctl.backend_type` enum value or a string that
             specifies a SYCL backend. Currently, accepted values are: "cuda",
             "opencl", "level_zero", or "all".
-        device_type (optional): Defaults to ``dpctl.device_type.all``.
+            Default: ``dpctl.backend_type.all``.
+        device_type (optional):
             A :class:`dpctl.device_type` enum value or a string that
             specifies a SYCL device type. Currently, accepted values are:
             "gpu", "cpu", "accelerator", "host", or "all".
+            Default: ``dpctl.device_type.all``.
     Returns:
-        int: The number of available SYCL devices that satisfy the provided
-        :class:`dpctl.backend_type` and :class:`dpctl.device_type` values.
+        int:
+            The number of available SYCL devices that satisfy the provided
+            :py:class:`dpctl.backend_type` and :py:class:`dpctl.device_type`
+            values.
     """
     cdef _backend_type BTy = _backend_type._ALL_BACKENDS
     cdef _device_type DTy = _device_type._ALL_DEVICES
@@ -248,8 +255,9 @@ cpdef cpp_bool has_cpu_devices():
     """ A helper function to check if there are any SYCL CPU devices available.
 
     Returns:
-        bool: ``True`` if ``sycl::device_type::cpu`` devices are present,
-        ``False`` otherwise.
+        bool:
+            ``True`` if ``sycl::device_type::cpu`` devices are present,
+            ``False`` otherwise.
     """
     cdef int num_cpu_dev = DPCTLDeviceMgr_GetNumDevices(_device_type._CPU)
     return <cpp_bool>num_cpu_dev
@@ -259,8 +267,9 @@ cpdef cpp_bool has_gpu_devices():
     """ A helper function to check if there are any SYCL GPU devices available.
 
     Returns:
-        bool: ``True`` if ``sycl::device_type::gpu`` devices are present,
-        ``False`` otherwise.
+        bool:
+            ``True`` if ``sycl::device_type::gpu`` devices are present,
+            ``False`` otherwise.
     """
     cdef int num_gpu_dev = DPCTLDeviceMgr_GetNumDevices(_device_type._GPU)
     return <cpp_bool>num_gpu_dev
@@ -271,8 +280,9 @@ cpdef cpp_bool has_accelerator_devices():
     available.
 
     Returns:
-        bool: ``True`` if ``sycl::device_type::accelerator`` devices are
-        present, ``False`` otherwise.
+        bool:
+            ``True`` if ``sycl::device_type::accelerator`` devices are
+            present, ``False`` otherwise.
     """
     cdef int num_accelerator_dev = DPCTLDeviceMgr_GetNumDevices(
         _device_type._ACCELERATOR
@@ -284,11 +294,13 @@ cpdef SyclDevice select_accelerator_device():
     """ A wrapper for SYCL's ``accelerator_selector`` class.
 
     Returns:
-        dpctl.SyclDevice: A Python object wrapping the SYCL ``device``
-        returned by the SYCL ``accelerator_selector``.
+        dpctl.SyclDevice:
+            A Python object wrapping the SYCL ``device``
+            returned by the SYCL ``accelerator_selector``.
     Raises:
-        dpctl.SyclDeviceCreatioError: If the SYCL ``accelerator_selector`` is
-        unable to select a ``device``.
+        dpctl.SyclDeviceCreationError:
+            If the SYCL ``accelerator_selector`` is
+            unable to select a ``device``.
     """
     cdef DPCTLSyclDeviceSelectorRef DSRef = DPCTLAcceleratorSelector_Create()
     cdef DPCTLSyclDeviceRef DRef = DPCTLDevice_CreateFromSelector(DSRef)
@@ -304,11 +316,13 @@ cpdef SyclDevice select_cpu_device():
     """ A wrapper for SYCL's ``cpu_selector`` class.
 
     Returns:
-        dpctl.SyclDevice: A Python object wrapping the SYCL ``device``
-        returned by the SYCL ``cpu_selector``.
+        dpctl.SyclDevice:
+            A Python object wrapping the SYCL ``device``
+            returned by the SYCL ``cpu_selector``.
     Raises:
-        dpctl.SyclDeviceCreationError: If the SYCL ``cpu_selector`` is
-        unable to select a ``device``.
+        dpctl.SyclDeviceCreationError:
+            If the SYCL ``cpu_selector`` is
+            unable to select a ``device``.
     """
     cdef DPCTLSyclDeviceSelectorRef DSRef = DPCTLCPUSelector_Create()
     cdef DPCTLSyclDeviceRef DRef = DPCTLDevice_CreateFromSelector(DSRef)
@@ -324,11 +338,13 @@ cpdef SyclDevice select_default_device():
     """ A wrapper for SYCL's ``default_selector`` class.
 
     Returns:
-        dpctl.SyclDevice: A Python object wrapping the SYCL ``device``
-        returned by the SYCL ``default_selector``.
+        dpctl.SyclDevice:
+            A Python object wrapping the SYCL ``device``
+            returned by the SYCL ``default_selector``.
     Raises:
-        dpctl.SyclDeviceCreationError: If the SYCL ``default_selector`` is
-        unable to select a ``device``.
+        dpctl.SyclDeviceCreationError:
+            If the SYCL ``default_selector`` is
+            unable to select a ``device``.
     """
     cdef DPCTLSyclDeviceSelectorRef DSRef = DPCTLDefaultSelector_Create()
     cdef DPCTLSyclDeviceRef DRef = DPCTLDevice_CreateFromSelector(DSRef)
@@ -344,11 +360,13 @@ cpdef SyclDevice select_gpu_device():
     """ A wrapper for SYCL's ``gpu_selector`` class.
 
     Returns:
-        dpctl.SyclDevice: A Python object wrapping the SYCL ``device``
-        returned by the SYCL ``gpu_selector``.
+        dpctl.SyclDevice:
+            A Python object wrapping the SYCL ``device``
+            returned by the SYCL ``gpu_selector``.
     Raises:
-        dpctl.SyclDeviceCreationError: If the SYCL ``gpu_selector`` is
-        unable to select a ``device``.
+        dpctl.SyclDeviceCreationError:
+            If the SYCL ``gpu_selector`` is
+            unable to select a ``device``.
     """
     cdef DPCTLSyclDeviceSelectorRef DSRef = DPCTLGPUSelector_Create()
     cdef DPCTLSyclDeviceRef DRef = DPCTLDevice_CreateFromSelector(DSRef)
@@ -393,10 +411,11 @@ _global_default_device_cache = ContextVar(
 
 
 cpdef SyclDevice _cached_default_device():
-    """Returns a cached devide selected by default selector.
+    """Returns a cached device selected by default selector.
 
     Returns:
-        :class:`dpctl.SyclDevice`: A cached default-selected SYCL device.
+        dpctl.SyclDevice:
+            A cached default-selected SYCL device.
 
     """
     cdef _DefaultDeviceCache _cache = _global_default_device_cache.get()

dpctl/_sycl_platform.pyx

@@ -85,12 +85,36 @@ cdef void _init_helper(_SyclPlatform platform, DPCTLSyclPlatformRef PRef):
 
 cdef class SyclPlatform(_SyclPlatform):
     """ SyclPlatform(self, arg=None)
-        Python class representing ``sycl::platform`` class.
+    Python class representing ``sycl::platform`` class.
 
-        SyclPlatform() - create platform selected by sycl::default_selector
-        SyclPlatform(filter_selector) - create platform selected by filter
-        selector
+    There are two ways of creating a SyclDevice instance:
+
+        - Invoking the constructor with no arguments creates a
+          platform using the default selector.
+
+        :Example:
+            .. code-block:: python
+
+                import dpctl
+
+                # Create a SyclPlatform for default-selected device
+                pl = dpctl.SyclPlatform()
+                print(pl.name, pl.version)
+
+        - Invoking the constructor with specific filter selector string that
+          creates a queue for the device corresponding to the filter string.
+
+        :Example:
+            .. code-block:: python
+
+                import dpctl
+
+                # Create a SyclPlatform for device selected by
+                # filter-selector string
+                pl = dpctl.SyclPlatform("opencl:cpu")
+                print(pl.name, pl.version)
     """
+
     @staticmethod
     cdef SyclPlatform _create(DPCTLSyclPlatformRef pref):
         """
@@ -340,11 +364,16 @@ def lsplatform(verbosity=0):
 
     :Example:
         On a system with an OpenCL CPU driver, OpenCL GPU driver,
-        Level Zero GPU driver, running the command. ::
+        Level Zero GPU driver, running the command:
+
+        .. code-block:: bash
+
+            $ python -c "import dpctl; dpctl.lsplatform(verbosity=2)"
 
-            $ python -c "import dpctl; dpctl.lsplatform()"
+        outputs
 
-        returns ::
+        .. code-block:: text
+            :caption: Sample output of lsplatform(verbosity=2)
 
             Platform 0::
                 Name        Intel(R) OpenCL
@@ -381,10 +410,10 @@ def lsplatform(verbosity=0):
                     Device type     gpu
 
     Args:
-        verbosity (optional): Defaults to 0.
+        verbosity (Literal[0,1,2], optional):
             The verbosity controls how much information is printed by the
             function. 0 is the lowest level set by default and 2 is the highest
-            level to print the most verbose output.
+            level to print the most verbose output. Default: `0`.
     """
     cdef DPCTLPlatformVectorRef PVRef = NULL
     cdef size_t v = 0