Split out Python API classes into separate pages.

  - All Python API classes are now documented under separate
    pages.
  - Add an autosummary to each class documentation page.
  - Rename dpCtl to dpctl in few places.

Author: Diptorup Deb

docs/conf.in

@@ -32,6 +32,7 @@ extensions = [
     "sphinx.ext.viewcode",
     "sphinx.ext.githubpages",
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
 ]
 
@@ -69,7 +70,7 @@ source_suffix = ".rst"
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
-highlight_language = "c"
+highlight_language = "Python"
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
@@ -140,3 +141,92 @@ if generate_multiversion == "ON":
         html_context["versions"].append(
             (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 sphinx.ext.autosummary import Autosummary
+from sphinx.ext.autosummary import get_documenter
+from docutils.parsers.rst import directives
+from sphinx.util.inspect import safe_getattr
+
+
+class AutoAutoSummary(Autosummary):
+    """Create a summary for methods and attributes (autosummary).
+    See https://stackoverflow.com/questions/20569011/python-sphinx-autosummary-automated-listing-of-member-functions
+    """
+
+    option_spec = {
+        "methods": directives.unchanged,
+        "private_methods": directives.unchanged,
+        "attributes": directives.unchanged,
+    }
+
+    required_arguments = 1
+
+    @staticmethod
+    def get_members(app, obj, typ, include_public=None):
+        if not include_public:
+            include_public = []
+        items = []
+        for name in sorted(obj.__dict__.keys()):
+            try:
+                documenter = get_documenter(app, safe_getattr(obj, name), obj)
+            except AttributeError:
+                continue
+            if documenter.objtype in typ:
+                items.append(name)
+        return items
+
+    def run(self):
+        clazz = str(self.arguments[0])
+        (module_name, class_name) = clazz.rsplit(".", 1)
+        m = __import__(module_name, globals(), locals(), [class_name])
+        c = getattr(m, class_name)
+        app = self.state.document.settings.env.app
+        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("_")
+            ]
+        if "private_methods" in self.options:
+            private_methods = self.get_members(app, c, ["method"], ["__init__"])
+            self.content = [
+                "%s" % method
+                for method in private_methods
+                if method.startswith("_") and not method.startswith("__")
+            ]
+        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("_")
+            ]
+        return super().run()
+
+
+def setup(app):
+    app.add_directive("autoautosummary", AutoAutoSummary)
+    app.add_autodocumenter(ClassMembersDocumenter)

docs/docfiles/dpctl.dptensor_api.rst

@@ -1,8 +1,8 @@
-.. _dpCtl.dptensor_api:
+.. _dpctl.dptensor_api:
 
-#########################
-dpctl dptensor Python API
-#########################
+##############
+dpctl.dptensor
+##############
 
 .. automodule:: dpctl.dptensor
     :members:

docs/docfiles/dpctl.memory_api.rst

@@ -1,8 +1,8 @@
-.. _dpCtl.memory_api:
+.. _dpctl.memory_api:
 
-#######################
-dpCtl Memory Python API
-#######################
+############
+dpctl.memory
+############
 
 .. automodule:: dpctl.memory
 

docs/docfiles/dpctl.program_api.rst

@@ -1,8 +1,8 @@
-.. _dpCtl.program_api:
+.. _dpctl.program_api:
 
-########################
-dpctl Program Python API
-########################
+#############
+dpctl.program
+#############
 
 .. automodule:: dpctl.program
 

docs/docfiles/dpctl_pyapi.rst

@@ -19,22 +19,14 @@ Sub-modules
 Classes
 -------
 
-.. autoclass:: dpctl.SyclContext
-    :members:
-    :undoc-members:
-
-.. autoclass:: dpctl.SyclDevice
-    :members:
-    :inherited-members:
-    :undoc-members:
-
-.. autoclass:: dpctl.SyclEvent
-    :members:
-    :undoc-members:
+.. toctree::
+    :maxdepth: 1
 
-.. autoclass:: dpctl.SyclQueue
-    :members:
-    :undoc-members:
+    dpctl_pyapi/SyclContext
+    dpctl_pyapi/SyclDevice
+    dpctl_pyapi/SyclEvent
+    dpctl_pyapi/SyclPlatform
+    dpctl_pyapi/SyclQueue
 
 Enumerations
 ------------

docs/docfiles/dpctl_pyapi/SyclContext.rst

@@ -0,0 +1,41 @@
+.. _SyclContext_api:
+
+#################
+dpctl.SyclContext
+#################
+
+.. autoclass:: dpctl.SyclContext
+
+    .. rubric:: Attributes:
+
+    .. autoautosummary:: dpctl.SyclContext
+        :attributes:
+
+    .. rubric:: Private methods:
+
+    .. autoautosummary:: dpctl.SyclContext
+        :private_methods:
+
+    .. rubric:: Public methods:
+
+    .. autoautosummary:: dpctl.SyclContext
+        :methods:
+
+Detail
+======
+
+Private methods
+---------------
+
+.. autoclassmembers:: dpctl.SyclContext
+    :noindex:
+    :private-members: _get_capsule
+
+
+Public methods
+--------------
+
+.. autoclassmembers:: dpctl.SyclContext
+    :noindex:
+    :members:
+    :undoc-members:

docs/docfiles/dpctl_pyapi/SyclDevice.rst

@@ -0,0 +1,28 @@
+.. _SyclDevice_api:
+
+################
+dpctl.SyclDevice
+################
+
+.. autoclass:: dpctl.SyclDevice
+
+    .. rubric:: Attributes:
+
+    .. autoautosummary:: dpctl.SyclDevice
+        :attributes:
+
+    .. rubric:: Public methods:
+
+    .. autoautosummary:: dpctl.SyclDevice
+        :methods:
+
+Detail
+======
+
+Public methods
+--------------
+
+.. autoclassmembers:: dpctl.SyclDevice
+    :noindex:
+    :members:
+    :undoc-members:

docs/docfiles/dpctl_pyapi/SyclEvent.rst

@@ -0,0 +1,10 @@
+.. _SyclEvent_api:
+
+###############
+dpctl.SyclEvent
+###############
+
+.. autoclass:: dpctl.SyclEvent
+    :members:
+    :inherited-members:
+    :undoc-members:

docs/docfiles/dpctl_pyapi/SyclPlatform.rst

@@ -0,0 +1,20 @@
+.. _SyclPlatform_api:
+
+##################
+dpctl.SyclPlatform
+##################
+
+
+.. autoclass:: dpctl.SyclPlatform
+
+
+Detail
+======
+
+Public methods
+--------------
+
+.. autoclassmembers:: dpctl.SyclPlatform
+    :noindex:
+    :members:
+    :undoc-members:

docs/docfiles/dpctl_pyapi/SyclQueue.rst

@@ -0,0 +1,41 @@
+.. _SyclQueue_api:
+
+###############
+dpctl.SyclQueue
+###############
+
+.. autoclass:: dpctl.SyclQueue
+
+    .. rubric:: Attributes:
+
+    .. autoautosummary:: dpctl.SyclQueue
+        :attributes:
+
+    .. rubric:: Private methods:
+
+    .. autoautosummary:: dpctl.SyclQueue
+        :private_methods:
+
+    .. rubric:: Public methods:
+
+    .. autoautosummary:: dpctl.SyclQueue
+        :methods:
+
+Detail
+======
+
+Private methods
+---------------
+
+.. autoclassmembers:: dpctl.SyclQueue
+    :noindex:
+    :private-members: _get_capsule
+    :undoc-members:
+
+Public methods
+--------------
+
+.. autoclassmembers:: dpctl.SyclQueue
+    :noindex:
+    :members:
+    :undoc-members: