Reorganize Python docs.

Diptorup Deb · Diptorup Deb · commit 7e4442c207ba · 2021-03-31T08:50:13.000-05:00
diff --git a/docs/dpctl_api.rst b/docs/dpctl_api.rst
@@ -9,26 +9,14 @@ dpctl Python API
 Classes
 -------
 
-.. autoclass:: dpctl.SyclContext
-    :members:
-    :undoc-members:
-
-.. autoclass:: dpctl.SyclDevice
-    :members:
-    :inherited-members:
-    :undoc-members:
-
-.. autoclass:: dpctl.SyclEvent
-    :members:
-    :undoc-members:
-
-.. autoclass:: dpctl.SyclPlatform
-    :members:
-    :undoc-members:
-
-.. autoclass:: dpctl.SyclQueue
-    :members:
-    :undoc-members:
+.. toctree::
+    :maxdepth: 1
+
+    dpctl_pyapi_classes/SyclContext
+    dpctl_pyapi_classes/SyclDevice
+    dpctl_pyapi_classes/SyclEvent
+    dpctl_pyapi_classes/SyclPlatform
+    dpctl_pyapi_classes/SyclQueue
 
 Enumerations
 ------------
diff --git a/docs/dpctl_pyapi_classes/SyclContext.rst b/docs/dpctl_pyapi_classes/SyclContext.rst
@@ -0,0 +1,9 @@
+.. _SyclContext_api:
+
+#################
+dpctl.SyclContext
+#################
+
+.. autoclass:: dpctl.SyclContext
+    :members:
+    :undoc-members:
diff --git a/docs/dpctl_pyapi_classes/SyclDevice.rst b/docs/dpctl_pyapi_classes/SyclDevice.rst
@@ -0,0 +1,10 @@
+.. _SyclDevice_api:
+
+################
+dpctl.SyclDevice
+################
+
+.. autoclass:: dpctl.SyclDevice
+    :members:
+    :inherited-members:
+    :undoc-members:
diff --git a/docs/dpctl_pyapi_classes/SyclEvent.rst b/docs/dpctl_pyapi_classes/SyclEvent.rst
@@ -0,0 +1,10 @@
+.. _SyclEvent_api:
+
+###############
+dpctl.SyclEvent
+###############
+
+.. autoclass:: dpctl.SyclEvent
+    :members:
+    :inherited-members:
+    :undoc-members:
diff --git a/docs/dpctl_pyapi_classes/SyclPlatform.rst b/docs/dpctl_pyapi_classes/SyclPlatform.rst
@@ -0,0 +1,9 @@
+.. _SyclPlatform_api:
+
+##################
+dpctl.SyclPlatform
+##################
+
+.. autoclass:: dpctl.SyclPlatform
+    :members:
+    :undoc-members:
diff --git a/docs/dpctl_pyapi_classes/SyclQueue.rst b/docs/dpctl_pyapi_classes/SyclQueue.rst
@@ -0,0 +1,9 @@
+.. _SyclQueue_api:
+
+###############
+dpctl.SyclQueue
+###############
+
+.. autoclass:: dpctl.SyclQueue
+    :members:
+    :undoc-members:
diff --git a/docs/toc_pyapi.rst b/docs/toc_pyapi.rst
@@ -1,5 +1,5 @@
 Python API
-================
+==========
 
 .. toctree::
     :maxdepth: 1
diff --git a/dpctl/__init__.py b/dpctl/__init__.py
@@ -17,18 +17,12 @@
 """
     **Data Parallel Control (dpctl)**
 
-    Dpctl provides a lightweight Python wrapper over a subset of
-    DPC++/SYCL's API. The goal of dpctl is not (yet) to provide a
-    abstraction for every SYCL function. Dpctl is intended to provide
-    a common runtime to manage specific SYCL resources, such as devices
-    and USM memory, for SYCL-based Python packages and extension modules.
+    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).
 
-    The main features presently provided by dpctl are:
+    Apart from the main SYCL runtime classes, dpctl includes a `memory` sub-module that exposes the SYCL USM allocators and deallocators.
 
-    * A SYCL queue manager exposed directly inside the top-level `dpctl`
-      module.
-    * 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."
 
