Docs/0.8.0 api docs (#477)

* Final few changes to API docs. * Add version entry of 0.8.0
IntelPython · May 26, 2021 · b38750d · b38750d
1 parent 7eafc30
commit b38750d
Show file tree

Hide file tree

Showing 11 changed files with 154 additions and 84 deletions.
diff --git a/docs/conf.in b/docs/conf.in
@@ -8,17 +8,21 @@
 # import os
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
-import textwrap
+from docutils.parsers.rst import directives
+from sphinx.ext.autosummary import Autosummary, get_documenter
+from sphinx.util.inspect import safe_getattr
+
+import dpctl
 
 # -- Project information -----------------------------------------------------
 
 project = "Data-parallel Control (dpctl)"
 copyright = "2020, Intel Corp."
 author = "Intel Corp."
 
-version = "@CURRENT_RELEASE@"
+version = dpctl.__version__.strip(".dirty")
 # The full version, including alpha/beta/rc tags
-release = "@CURRENT_RELEASE@"
+release = dpctl.__version__.strip(".dirty")
 
 
 # -- General configuration ---------------------------------------------------
@@ -53,7 +57,9 @@ if use_doxyrest == "ON":
     # rst files.
     import fileinput
 
-    with fileinput.FileInput("@DOXYREST_OUTPUT_DIR@/global.rst", inplace=True) as file:
+    with fileinput.FileInput(
+        "@DOXYREST_OUTPUT_DIR@/global.rst", inplace=True
+    ) as file:
         for line in file:
             print(line.replace("typedefDPCTL_C_EXTERN_C_BEGIN", ""), end="")
 
@@ -143,36 +149,6 @@ if generate_multiversion == "ON":
             (version, DOC_SITE_NAME + version + "/index.html")
         )
 
-# Add an "autoclassmembers" directive that acts the same way as
-# "autoclass", but does not print out the class doc.
-
-from sphinx.ext.autodoc import ClassDocumenter, ObjectMembers
-from sphinx.ext.autodoc.importer import get_class_members
-
-
-class ClassMembersDocumenter(ClassDocumenter):
-    """
-    Documenter for only class members and skips the class and __init__
-    docstrings.
-    """
-
-    objtype = "classmembers"
-
-    def add_directive_header(self, sig):
-        pass
-
-    def get_doc(self, encoding=None, ignore=None):
-        return None
-
-
-# Add an "autoautosummary" directive to add a summary table of class
-# members and attributes.
-# See https://stackoverflow.com/questions/20569011/python-sphinx-autosummary-automated-listing-of-member-functions
-
-from docutils.parsers.rst import directives
-from sphinx.ext.autosummary import Autosummary, get_documenter
-from sphinx.util.inspect import safe_getattr
-
 
 class AutoAutoSummary(Autosummary):
     """Create a summary for methods and attributes (autosummary).
@@ -210,7 +186,9 @@ class AutoAutoSummary(Autosummary):
         if "methods" in self.options:
             methods = self.get_members(app, c, ["method"], ["__init__"])
             self.content = [
-                "%s" % method for method in methods if not method.startswith("_")
+                "%s" % method
+                for method in methods
+                if not method.startswith("_")
             ]
         if "private_methods" in self.options:
             private_methods = self.get_members(app, c, ["method"], ["__init__"])
@@ -222,11 +200,12 @@ class AutoAutoSummary(Autosummary):
         if "attributes" in self.options:
             attribs = self.get_members(app, c, ["attribute", "property"])
             self.content = [
-                "%s" % attrib for attrib in attribs if not attrib.startswith("_")
+                "%s" % attrib
+                for attrib in attribs
+                if not attrib.startswith("_")
             ]
         return super().run()
 
 
 def setup(app):
     app.add_directive("autoautosummary", AutoAutoSummary)
-    app.add_autodocumenter(ClassMembersDocumenter)
diff --git a/docs/doc_versions.txt b/docs/doc_versions.txt
@@ -1,3 +1,4 @@
+0.8.0
 0.7.0
 0.6.1
 latest
diff --git a/docs/docfiles/dpctl.memory_api.rst b/docs/docfiles/dpctl.memory_api.rst
@@ -28,22 +28,3 @@ Functions
 ---------
 
 .. autofunction:: dpctl.memory.as_usm_memory
-
-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.
-
-DeviceBuffer stores a unique pointer to an instance of this class. DeviceBuffer implements ``__cuda_array_interface__``. Direct constructors always allocate
-new memory and copy provided inputs into the newly allocated array.
-
-Zero-copy construction is possible from a ``unique_ptr<device_ buffer>``, with
-the ownership being moved to the Cython extension instance.
-
-DeviceBuffer provides ``__reduce__`` method to support pickling (which works by copying content of the device buffer to host) and provides the following set of routines, among others:
-
-    - ``copy_to_host(host_buf_obj)`` to copy content of the underlying device_buffer to a host buffer
-    - ``copy_from_host(host_buf_obf)`` to copy content of the host buffer into memory of underlying device_buffer
-    - ``copy_from_device(cuda_ary_obj)`` to copy device memory underlying cuda_ary_obj Python object implementing ``__cuda_array_interface__`` to the memory underlying DeviceBuffer instance.
-
-RMM's methods are declared nogil.
diff --git a/docs/docfiles/dpctl_pyapi.rst b/docs/docfiles/dpctl_pyapi.rst
@@ -4,6 +4,8 @@
 dpctl Python API
 ################
 
+.. currentmodule:: dpctl
+
 .. automodule:: dpctl
 
 Sub-modules
@@ -26,11 +28,11 @@ Classes
 .. toctree::
     :maxdepth: 1
 
-    dpctl_pyapi/SyclContext
-    dpctl_pyapi/SyclDevice
-    dpctl_pyapi/SyclEvent
-    dpctl_pyapi/SyclPlatform
-    dpctl_pyapi/SyclQueue
+    dpctl.SyclContext : A Python class representing cl::sycl::context <dpctl_pyapi/SyclContext>
+    dpctl.SyclDevice : A Python class representing cl::sycl::device <dpctl_pyapi/SyclDevice>
+    dpctl.SyclEvent : A Python class representing cl::sycl::event <dpctl_pyapi/SyclEvent>
+    dpctl.SyclPlatform : A Python class representing cl::sycl::event <dpctl_pyapi/SyclPlatform>
+    dpctl.SyclQueue : A Python class representing cl::sycl::event <dpctl_pyapi/SyclQueue>
 
 Enumerations
 ------------

diff --git a/docs/docfiles/dpctl_pyapi/SyclContext.rst b/docs/docfiles/dpctl_pyapi/SyclContext.rst
@@ -4,6 +4,8 @@
 dpctl.SyclContext
 #################
 
+.. currentmodule:: dpctl
+
 .. autoclass:: dpctl.SyclContext
 
     .. rubric:: Attributes:

diff --git a/docs/docfiles/dpctl_pyapi/SyclDevice.rst b/docs/docfiles/dpctl_pyapi/SyclDevice.rst
@@ -4,7 +4,9 @@
 dpctl.SyclDevice
 ################
 
-.. autoclass:: dpctl.SyclDevice
+.. currentmodule:: dpctl
+
+.. autoclass:: SyclDevice
 
     .. rubric:: Attributes:
 

diff --git a/docs/docfiles/dpctl_pyapi/SyclEvent.rst b/docs/docfiles/dpctl_pyapi/SyclEvent.rst
@@ -4,14 +4,15 @@
 dpctl.SyclEvent
 ###############
 
+.. currentmodule:: dpctl
+
 .. autoclass:: dpctl.SyclEvent
 
     .. rubric:: Public methods:
 
     .. autoautosummary:: dpctl.SyclEvent
         :methods:
 
-
 Detail
 ======
 

diff --git a/docs/docfiles/dpctl_pyapi/SyclPlatform.rst b/docs/docfiles/dpctl_pyapi/SyclPlatform.rst
@@ -4,6 +4,7 @@
 dpctl.SyclPlatform
 ##################
 
+.. currentmodule:: dpctl
 
 .. autoclass:: dpctl.SyclPlatform
 
@@ -12,11 +13,6 @@ dpctl.SyclPlatform
     .. autoautosummary:: dpctl.SyclPlatform
         :attributes:
 
-    .. rubric:: Private methods:
-
-    .. autoautosummary:: dpctl.SyclPlatform
-        :private_methods:
-
     .. rubric:: Public methods:
 
     .. autoautosummary:: dpctl.SyclPlatform

diff --git a/docs/docfiles/dpctl_pyapi/SyclQueue.rst b/docs/docfiles/dpctl_pyapi/SyclQueue.rst
@@ -4,6 +4,8 @@
 dpctl.SyclQueue
 ###############
 
+.. currentmodule:: dpctl
+
 .. autoclass:: dpctl.SyclQueue
 
     .. rubric:: Attributes:
-Original file line number
+Diff line change
@@ -1,3 +1,4 @@
+.8.0
 .7.0
 .6.1
     latest