Doc improvements (#232)

* Some more improvements to the Python API documentation.
* Restructure how various module members are displayed, now broken into Classes, Exceptions, Functions
* Include `undoc-members` and `inherited-members`
* More fixes to docstring errors. Document exception classes in sycl_core.
* Change the dpctl's module level docstring.

Author: diptorupd

docs/dpCtl.dptensor_api.rst

@@ -6,3 +6,4 @@ dpCtl dptensor Python API
 
 .. automodule:: dpctl.dptensor
     :members:
+    :undoc-members:

docs/dpCtl.memory_api.rst

@@ -5,11 +5,27 @@ dpCtl Memory Python API
 #######################
 
 .. automodule:: dpctl.memory
+
+Classes
+-------
+
+.. autoclass:: dpctl.memory.MemoryUSMDevice
     :members:
+    :inherited-members:
+    :undoc-members:
 
-....
+.. autoclass:: dpctl.memory.MemoryUSMHost
+    :members:
+    :inherited-members:
+    :undoc-members:
+
+.. autoclass:: dpctl.memory.MemoryUSMShared
+    :members:
+    :inherited-members:
+    :undoc-members:
 
-**Comparing dpctl.memory to Rapids Memory Manager (RMM)**
+Comparison with Rapids Memory Manager (RMM)
+-------------------------------------------
 
 RMM implements DeviceBuffer which is Cython native class wrapping around something similar to ``std::vector<unsigned char, custom_cuda_allocator (calls resource manager)>`` which is called device_buffer.
 

docs/dpCtl.program_api.rst

@@ -5,4 +5,25 @@ dpCtl Program Python API
 ########################
 
 .. automodule:: dpctl.program
+
+Classes
+-------
+
+.. autoclass:: dpctl.program.SyclKernel
+    :members:
+    :undoc-members:
+
+.. autoclass:: dpctl.program.SyclProgram
     :members:
+    :undoc-members:
+
+Exceptions
+----------
+
+.. autoexception::  dpctl.program.SyclProgramCompilationError
+
+Functions
+---------
+
+.. autofunction:: create_program_from_source
+.. autofunction:: create_program_from_spirv

docs/dpCtl_api.rst

@@ -5,4 +5,58 @@ dpCtl Python API
 ################
 
 .. automodule:: dpctl
-   :members:
+
+Classes
+-------
+
+.. autoclass:: dpctl.SyclContext
+    :members:
+    :undoc-members:
+
+.. autoclass:: dpctl.SyclDevice
+    :members:
+    :undoc-members:
+
+.. autoclass:: dpctl.SyclEvent
+    :members:
+    :undoc-members:
+
+.. autoclass:: dpctl.SyclQueue
+    :members:
+    :undoc-members:
+
+Enumerations
+------------
+
+.. autoclass:: dpctl.backend_type
+    :members:
+
+.. autoclass:: dpctl.device_type
+    :members:
+
+Exceptions
+----------
+
+.. autoexception:: dpctl.SyclKernelInvalidRangeError
+.. autoexception:: dpctl.SyclKernelSubmitError
+.. autoexception:: dpctl.SyclQueueCreationError
+.. autoexception:: dpctl.UnsupportedBackendError
+.. autoexception:: dpctl.UnsupportedDeviceError
+
+Functions
+---------
+
+.. autofunction:: device_context
+.. autofunction:: dump
+.. autofunction:: get_current_backend
+.. autofunction:: get_current_device_type
+.. autofunction:: get_current_queue
+.. autofunction:: get_include
+.. autofunction:: get_num_activated_queues
+.. autofunction:: get_num_platforms
+.. autofunction:: get_num_queues
+.. autofunction:: has_cpu_queues
+.. autofunction:: has_gpu_queues
+.. autofunction:: has_sycl_platforms
+.. autofunction:: is_in_device_context
+.. autofunction:: set_default_queue

docs/index.rst

@@ -22,6 +22,5 @@ Indices and tables
     :maxdepth: 3
     :caption: Contents:
 
-    self
     toc_pyapi
     api/dpCtl-CAPI_root

docs/toc_pyapi.rst

@@ -5,6 +5,6 @@ Python API
     :maxdepth: 1
 
     dpctl - SYCL runtime wrapper classes and queue manager <dpCtl_api>
-    dpctl.memory - USM memory manager <dpCtl.memory_api>
     dpctl.dptensor - Data-parallel tensor containers <dpCtl.dptensor_api>
+    dpctl.memory - USM memory manager <dpCtl.memory_api>
     dpctl.program - Program manager <dpCtl.program_api>

dpctl/__init__.py

@@ -30,10 +30,8 @@
 
     * A SYCL queue manager exposed directly inside the top-level `dpctl`
       module.
-    * A USM memory manager (`dpctl.memory`) that provides Python objects
-      implementing the Python buffer protocol using USM shared and USM host
-      allocators. The memory manager also exposes various utility functions
-      to wrap SYCL's USM allocators, deallocators, `memcpy` functions, *etc.*
+    * Python wrapper classes for the main SYCL runtime classes mentioned in
+      Section 4.6 of SYCL provisional 2020 spec (https://bit.ly/3asQx07).
 """
 __author__ = "Intel Corp."
 

dpctl/_sycl_core.pyx

@@ -52,7 +52,12 @@ __all__ = [
     "SyclContext",
     "SyclDevice",
     "SyclEvent",
-    "SyclQueue"
+    "SyclQueue",
+    "SyclKernelInvalidRangeError",
+    "SyclKernelSubmitError",
+    "SyclQueueCreationError",
+    "UnsupportedBackendError",
+    "UnsupportedDeviceError",
 ]
 
 _logger = logging.getLogger(__name__)
@@ -65,10 +70,10 @@ class device_type(Enum):
     ==================   ============
     Device type          Enum value
     ==================   ============
-    GPU                  1
-    CPU                  2
-    Accelerator          3
-    Host                 4
+    gpu                  1
+    cpu                  2
+    accelerator          3
+    host_device          4
     ==================   ============
 
     """
@@ -84,10 +89,10 @@ class backend_type(Enum):
     ==================   ============
     Name of backend      Enum value
     ==================   ============
-    OpenCL               1
-    Level Zero           2
-    Cuda                 3
-    Host                 4
+    opencl               1
+    level_zero           2
+    cuda                 3
+    host                 4
     ==================   ============
 
     """
@@ -96,38 +101,50 @@ class backend_type(Enum):
     cuda = auto()
     host = auto()
 
-cdef class UnsupportedBackendError (Exception):
-    """This exception is raised when a device type other than CPU or GPU is
-       encountered.
+cdef class UnsupportedBackendError(Exception):
+    """
+    An UnsupportedBackendError exception is raised when a backend value
+    is other than `backend_type.opencl` or `backend_type.level_zero` is
+    encountered. All other backends are currently not supported.
+
     """
     pass
 
-cdef class UnsupportedDeviceError (Exception):
-    """This exception is raised when a device type other than CPU or GPU is
-       encountered.
+cdef class UnsupportedDeviceError(Exception):
+    """
+    An UnsupportedDeviceError exception is raised when a device type value
+    other than `device_type.cpu` or `device_type.gpu` is encountered.
+
     """
     pass
 
-cdef class SyclKernelSubmitError (Exception):
-    """This exception is raised when a SYCL program could not be built from
-       either a SPIR-V binary file or a string source.
+cdef class SyclKernelSubmitError(Exception):
+    """
+    A SyclKernelSubmitError exception is raised when the provided
+    :class:`.SyclKernel` could not be submitted to the :class:`.SyclQueue`.
+
     """
     pass
 
-cdef class SyclKernelInvalidRangeError (Exception):
-    """This exception is raised when a range that has more than three
-       dimensions or less than one dimension.
+cdef class SyclKernelInvalidRangeError(Exception):
+    """
+    A SyclKernelInvalidRangeError is raised when the provided range has less
+    than one or more than three dimensions.
     """
     pass
 
-cdef class SyclQueueCreationError (Exception):
-    """This exception is raised when a range that has more than three
-       dimensions or less than one dimension.
+cdef class SyclQueueCreationError(Exception):
+    """
+    A SyclQueueCreationError exception is raised when a :class:`.SyclQueue`
+    could not be created. :class:`.SyclQueue` creation can fail if the filter
+    string is invalid, or the backend or device type values are not supported.
+
     """
     pass
 
 cdef class SyclContext:
-
+    """ Python wrapper class for cl::sycl::context.
+    """
     @staticmethod
     cdef SyclContext _create (DPCTLSyclContextRef ctxt):
         cdef SyclContext ret = SyclContext.__new__(SyclContext)
@@ -147,17 +164,17 @@ cdef class SyclContext:
         return self._ctxt_ref
 
     def addressof_ref (self):
-        """Returns the address of the DPCTLSyclContextRef pointer as a
-        long.
+        """
+        Returns the address of the DPCTLSyclContextRef pointer as a size_t.
 
         Returns:
             The address of the DPCTLSyclContextRef object used to create this
-            SyclContext cast to a long.
+            SyclContext cast to a size_t.
         """
         return int(<size_t>self._ctx_ref)
 
 cdef class SyclDevice:
-    """ Wrapper class for a Sycl Device
+    """ Python wrapper class for cl::sycl::device.
     """
 
     @staticmethod
@@ -274,17 +291,17 @@ cdef class SyclDevice:
         return self._device_ref
 
     def addressof_ref (self):
-        """Returns the address of the DPCTLSyclDeviceRef pointer as a
-        long.
+        """
+        Returns the address of the DPCTLSyclDeviceRef pointer as a size_t.
 
         Returns:
             The address of the DPCTLSyclDeviceRef object used to create this
-            SyclDevice cast to a long.
+            SyclDevice cast to a size_t.
         """
         return int(<size_t>self._device_ref)
 
 cdef class SyclEvent:
-    """ Wrapper class for a Sycl Event
+    """ Python wrapper class for cl::sycl::event.
     """
 
     @staticmethod
@@ -308,18 +325,18 @@ cdef class SyclEvent:
 
     def addressof_ref (self):
         """ Returns the address of the C API DPCTLSyclEventRef pointer as
-        a long.
+        a size_t.
 
         Returns:
             The address of the DPCTLSyclEventRef object used to create this
-            SyclEvent cast to a long.
+            SyclEvent cast to a size_t.
         """
         return int(<size_t>self._event_ref)
 
 import ctypes
 
 cdef class SyclQueue:
-    """ Wrapper class for a Sycl queue.
+    """ Python wrapper class for cl::sycl::queue.
     """
 
     @staticmethod
@@ -464,11 +481,12 @@ cdef class SyclQueue:
         return self._queue_ref
 
     def addressof_ref (self):
-        """ Returns the address of the C API DPCTLSyclQueueRef pointer as a long.
+        """
+        Returns the address of the C API DPCTLSyclQueueRef pointer as a size_t.
 
         Returns:
             The address of the DPCTLSyclQueueRef object used to create this
-            SyclQueue cast to a long.
+            SyclQueue cast to a size_t.
         """
         return int(<size_t>self._queue_ref)
 
@@ -618,7 +636,7 @@ cdef class SyclQueue:
 
 
 cdef class _SyclRTManager:
-    """ Wrapper for the C API's sycl queue manager interface.
+    """ Provides a wrapper for dpCtl's SYCL queue manager interface.
     """
     cdef dict _backend_str_ty_dict
     cdef dict _device_str_ty_dict
@@ -1010,7 +1028,7 @@ from contextlib import contextmanager
 @contextmanager
 def device_context(str queue_str="opencl:gpu:0"):
     """
-    Yeilds a SYCL queue corresponding to the input filter string.
+    Yields a SYCL queue corresponding to the input filter string.
 
     This context manager "activates", *i.e.*, sets as the currently usable
     queue, the SYCL queue defined by the "backend:device type:device id" tuple.
@@ -1025,7 +1043,8 @@ def device_context(str queue_str="opencl:gpu:0"):
         "backend:device-type:device-id", defaults to "opencl:gpu:0".
 
     Yields:
-        SyclQueue: A SYCL queue corresponding to the specified filter string.
+        :class:`.SyclQueue`: A SYCL queue corresponding to the specified \
+        filter string.
 
     Raises:
         ValueError: If the filter string is malformed.