Doc fixes. (#428)

* Doc updates for current master.

Author: Diptorup Deb

docs/doc_versions.txt

@@ -1,2 +1,3 @@
+0.7.0
 0.6.1
 latest

docs/docfiles/dpctl.dptensor_api.rst

@@ -0,0 +1,9 @@
+.. _dpctl.tensor_api:
+
+############
+dpctl.tensor
+############
+
+.. automodule:: dpctl.tensor
+    :members:
+    :undoc-members:

docs/docfiles/dpctl.tensor_api.rst

@@ -9,12 +9,16 @@ dpctl Python API
 Sub-modules
 -----------
 
-.. toctree::
-    :maxdepth: 1
-
-    dpctl.dptensor_api
-    dpctl.memory_api
-    dpctl.program_api
+    :mod:`dpctl.memory`
+        USM allocators and deallocators and classes that implement Python's
+        `buffer protocol`_.
+    :mod:`dpctl.program`
+        Experimental wrappers for SYCL 1.2 ``program`` and ``kernel`` classes.
+        The module is going to be refactored in the future to support SYCL
+        2020's ``kernel_bundle`` feature and the wrapper for the ``program``
+        class is going to be removed.
+    :mod:`dpctl.tensor`
+        Implementation of different types of tensor classes that use USM memory.
 
 Classes
 -------
@@ -44,8 +48,8 @@ Exceptions
 .. autoexception:: dpctl.SyclKernelSubmitError
 .. autoexception:: dpctl.SyclQueueCreationError
 
-Functions
----------
+Device Selection Functions
+--------------------------
 
 .. autofunction:: get_devices
 .. autofunction:: select_accelerator_device
@@ -58,12 +62,23 @@ Functions
 .. autofunction:: has_gpu_devices
 .. autofunction:: has_accelerator_devices
 .. autofunction:: has_host_device
-.. autofunction:: get_platforms
-.. autofunction:: lsplatform
+
+DPCTL Queue Management Functions
+--------------------------------
+
 .. autofunction:: device_context
 .. autofunction:: get_current_backend
 .. autofunction:: get_current_device_type
 .. autofunction:: get_current_queue
 .. autofunction:: get_num_activated_queues
 .. autofunction:: is_in_device_context
 .. autofunction:: set_global_queue
+
+Other Helper Functions
+----------------------
+.. autofunction:: get_platforms
+.. autofunction:: lsplatform
+
+.. _Section 4.6: https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#_sycl_runtime_classes
+.. _SYCL 2020 spec: https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html
+.. _buffer protocol: https://docs.python.org/3/c-api/buffer.html

docs/docfiles/dpctl_pyapi.rst

@@ -15,15 +15,19 @@
 # limitations under the License.
 
 """
-    **Data Parallel Control (dpctl)**
+    **Data Parallel Control (dpctl)** is a Python abstraction layer over SYCL.
 
-    Dpctl's Python API implements Python wrappers for a subset of DPC++/SYCL's
-    API. The Python API exposes wrappers for the SYCL runtime classes (expect
-    ``device_selector``) described in Section 4.6 of the
-    [SYCL 2020 spec](https://www.khronos.org/registry/SYCL/specs/sycl-2020/
-html/sycl-2020.html#_sycl_runtime_classes).
-    Apart from the main SYCL runtime classes, dpctl includes a `memory`
-    sub-module that exposes the SYCL USM allocators and deallocators.
+    Dpctl implements a subset of SYCL's API providing wrappers for the
+    SYCL runtime classes described in `Section 4.6`_ of the `SYCL 2020 spec`_.
+    Note that the SYCL ``device_selector`` class is not implemented, instead
+    there are device selection helper functions that can be used to simulate
+    the same behavior. Dpctl implements the ``ONEPI::filter_selector`` extension
+    that is included in Intel's DPC++ SYCL compiler.
+
+    The module also includes a global SYCL queue manager. The queue manager
+    provides convenience functions to create a global instance of
+    a :class:`dpctl.SyclQueue`, to create a nested stack of queue objects, and
+    to create a queue object for use only within a specific scope.
 """
 __author__ = "Intel Corp."
 

dpctl/__init__.py

@@ -266,11 +266,11 @@ cpdef SyclDevice select_accelerator_device():
     """ A wrapper for SYCL's ``accelerator_selector`` class.
 
     Returns:
-        A new class:`dpctl.SyclDevice` object containing the SYCL device
-        returned by the ``accelerator_selector``.
+        dpctl.SyclDevice: A Python object wrapping the SYCL ``device``
+        returned by the SYCL ``accelerator_selector``.
     Raises:
-        A ``ValueError`` is raised if the SYCL ``accelerator_selector`` is
-        unable to select a device.
+        ValueError: If the SYCL ``accelerator_selector`` is unable to select a
+                    ``device``.
     """
     cdef DPCTLSyclDeviceSelectorRef DSRef = DPCTLAcceleratorSelector_Create()
     cdef DPCTLSyclDeviceRef DRef = DPCTLDevice_CreateFromSelector(DSRef)
@@ -286,11 +286,11 @@ cpdef SyclDevice select_cpu_device():
     """ A wrapper for SYCL's ``cpu_selector`` class.
 
     Returns:
-        A new class:`dpctl.SyclDevice` object containing the SYCL device
-        returned by the ``cpu_selector``.
+        dpctl.SyclDevice: A Python object wrapping the SYCL ``device``
+        returned by the SYCL ``cpu_selector``.
     Raises:
-        A ``ValueError`` is raised if the SYCL ``cpu_selector`` is unable to
-        select a device.
+        ValueError: If the SYCL ``cpu_selector`` is unable to select a
+                    ``device``.
     """
     cdef DPCTLSyclDeviceSelectorRef DSRef = DPCTLCPUSelector_Create()
     cdef DPCTLSyclDeviceRef DRef = DPCTLDevice_CreateFromSelector(DSRef)
@@ -306,11 +306,11 @@ cpdef SyclDevice select_default_device():
     """ A wrapper for SYCL's ``default_selector`` class.
 
     Returns:
-        A new class:`dpctl.SyclDevice` object containing the SYCL device
-        returned by the ``default_selector``.
+        dpctl.SyclDevice: A Python object wrapping the SYCL ``device``
+        returned by the SYCL ``default_selector``.
     Raises:
-        A ``ValueError`` is raised if the SYCL ``default_selector`` is unable to
-        select a device.
+        ValueError: If the SYCL ``default_selector`` is unable to select a
+            ``device``.
     """
     cdef DPCTLSyclDeviceSelectorRef DSRef = DPCTLDefaultSelector_Create()
     cdef DPCTLSyclDeviceRef DRef = DPCTLDevice_CreateFromSelector(DSRef)
@@ -326,11 +326,11 @@ cpdef SyclDevice select_gpu_device():
     """ A wrapper for SYCL's ``gpu_selector`` class.
 
     Returns:
-        A new class:`dpctl.SyclDevice` object containing the SYCL device
-        returned by the ``gpu_selector``.
+        dpctl.SyclDevice: A Python object wrapping the SYCL ``device``
+        returned by the SYCL ``gpu_selector``.
     Raises:
-        A ``ValueError`` is raised if the SYCL `gpu_selector` is unable to
-        select a device.
+        ValueError: If the SYCL ``gpu_selector`` is unable to select a
+                    ``device``.
     """
     cdef DPCTLSyclDeviceSelectorRef DSRef = DPCTLGPUSelector_Create()
     cdef DPCTLSyclDeviceRef DRef = DPCTLDevice_CreateFromSelector(DSRef)
@@ -346,11 +346,11 @@ cpdef SyclDevice select_host_device():
     """ A wrapper for SYCL's ``host_selector`` class.
 
     Returns:
-        A new class:`dpctl.SyclDevice` object containing the SYCL device
-        returned by the ``host_selector``.
+        dpctl.SyclDevice: A Python object wrapping the SYCL ``device``
+        returned by the SYCL ``host_selector``.
     Raises:
-        A ``ValueError`` is raised if the SYCL ``host_selector`` is unable to
-        select a device.
+        ValueError: If the SYCL ``host_selector`` is unable to select a
+            ``device``.
     """
     cdef DPCTLSyclDeviceSelectorRef DSRef = DPCTLHostSelector_Create()
     cdef DPCTLSyclDeviceRef DRef = DPCTLDevice_CreateFromSelector(DSRef)

dpctl/_sycl_device_factory.pyx

@@ -144,10 +144,9 @@ cdef class _SyclQueueManager:
         or created from given arguments.
 
         Args:
-            A SyclQueue instance to be used as a global queue.
-            Alternatively, a filter selector string, or a SyclDevice
-            instance to be used to construct SyclQueue.
-
+            arg: An instance of :class:`dpctl.SyclQueue` or a filter selector
+                string to be used to construct a :class:`dpctl.SyclQueue`. The
+                queue is stored in the dpctl queue manager as the default queue.
         Raises:
             SyclQueueCreationError: If a SYCL queue could not be created.
         """

dpctl/_sycl_queue_manager.pyx

@@ -23,7 +23,8 @@
 
     Available tensor implementations:
 
-    * ``numpy_usm_shared``: Provides a ``numpy.ndarray`` sub-class whose
-       underlying memory buffer is allocated with a USM shared memory allocator.
+    ``numpy_usm_shared``:
+        Provides a ``numpy.ndarray`` sub-class whose underlying memory buffer
+        is allocated with a USM shared memory allocator.
 
 """