Fix documentation: DeviceProperties display and sidebar navigation (#1444)

* Fix DeviceProperties documentation by using cyclass.rst template

DeviceProperties is a Cython cdef class, but was being documented
without specifying the cyclass.rst template. This caused Sphinx to
use the default class template which uses autoproperty, which doesn't
work correctly with Cython extension types.

The cyclass.rst template uses autoattribute instead, which properly
documents the properties of Cython classes.

Fixes #1215

* Enable object entries in table of contents for sidebar navigation

Add toc_object_entries=True to all conf.py files to include object
descriptions (methods, attributes, etc.) in the table of contents.
This is a Sphinx 5.1+ feature that should enable the 'On This Page'
sidebar to show class methods and properties.

Also set toc_object_entries_show_parents='hide' for cleaner display
without redundant parent class names.

Partially addresses #1100

* List class members directly without separate sections in autosummary templates

Update autosummary templates (class.rst, cyclass.rst, protocol.rst) to
list methods and attributes directly under the class without separate
section headings. Methods are listed first, followed by attributes.

Combined with toc_object_entries=True in conf.py, individual methods
and attributes will appear directly in the 'On This Page' sidebar,
providing navigation similar to what was available in older versions
with the furo theme.

Fixes #1100

* Show class prefix in sidebar TOC, plain names in main docs

Change toc_object_entries_show_parents from 'hide' to 'domain' so that
the sidebar TOC shows class-prefixed names (e.g., Device.allocate())
while the main documentation shows just the method/attribute names.

Fixed template indentation to ensure automethod/autoattribute directives
are properly nested inside the autoclass block.

* Use autoclass :members: option for automatic member documentation

* Use section headings for methods/attributes to appear in sidebar TOC

* Fix autodoc directives to use fully qualified names

* Use autoclass :members: with toc_object_entries for sidebar

* Restore original template structure with rubrics

This restores the original template formatting where Methods and Attributes
are organized under rubric headings (which don't appear in TOC).

Note: pydata-sphinx-theme's secondary sidebar only shows document headings,
not autodoc entries. Methods/attributes won't appear in the sidebar without
using actual section headings, which would add extra headers to the main body.

* Configure pydata-sphinx-theme secondary sidebar for autodoc entries

- Add secondary_sidebar_items with page-toc and sourcelink
- Set show_toc_level: 3 to show more TOC levels by default
- Keep toc_object_entries = True for Sphinx to add object entries to TOC

This should make autodoc entries appear in the secondary sidebar if
Sphinx's toc_object_entries properly populates the page TOC.

* Remove sourcelink from secondary sidebar

* Apply cyclass.rst template to all Cython cdef classes

Public API Cython classes now using cyclass.rst:
- Buffer, MemoryResource
- Stream, StreamOptions
- Event, EventOptions
- DeviceMemoryResource, DeviceMemoryResourceOptions
- PinnedMemoryResource, PinnedMemoryResourceOptions
- ManagedMemoryResource, ManagedMemoryResourceOptions
- LaunchConfig

Private API Cython classes now using cyclass.rst:
- IPCAllocationHandle, IPCBufferDescriptor
- DeviceProperties (already was)

* Fix template assignments: dataclasses stay under dataclass.rst

- Cython dataclasses (StreamOptions, EventOptions, *ResourceOptions)
  stay under dataclass.rst template
- Pure Cython cdef classes (Buffer, Stream, Event, MemoryResource,
  LaunchConfig) use cyclass.rst template
- Classes inheriting from Cython (GraphMemoryResource,
  LegacyPinnedMemoryResource, VirtualMemoryResource) use cyclass.rst
- Restored original ordering

* Move LaunchConfig to dataclass template

- Device, Graph, GraphBuilder are regular Python classes (use default)
- LaunchConfig uses dataclass template per project convention

Author: kkraus14

cuda_bindings/docs/source/conf.py

@@ -53,6 +53,12 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
+# Include object entries (methods, attributes, etc.) in the table of contents
+# This enables the "On This Page" sidebar to show class methods and properties
+# Requires Sphinx 5.1+
+toc_object_entries = True
+toc_object_entries_show_parents = "domain"
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -69,6 +75,10 @@
         "version-switcher",
         "navbar-nav",
     ],
+    # Use custom secondary sidebar that includes autodoc entries
+    "secondary_sidebar_items": ["page-toc"],
+    # Show more TOC levels by default
+    "show_toc_level": 3,
 }
 if os.environ.get("CI"):
     if int(os.environ.get("BUILD_PREVIEW", 0)):

cuda_core/docs/source/_templates/autosummary/cyclass.rst

@@ -7,14 +7,6 @@
 
 .. autoclass:: {{ objname }}
 
-   {% block attributes %}
-   {% if attributes %}
-   {% for item in attributes %}
-   .. autoattribute:: {{ item }}
-   {%- endfor %}
-   {% endif %}
-   {% endblock %}
-
    {% block methods %}
    {% if methods %}
    .. rubric:: {{ _('Methods') }}
@@ -25,3 +17,13 @@
 
    {% endif %}
    {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   {% for item in attributes %}
+   .. autoattribute:: {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

cuda_core/docs/source/api.rst

@@ -23,6 +23,9 @@ CUDA runtime
    Graph
    GraphBuilder
    launch
+
+   :template: autosummary/cyclass.rst
+
    Buffer
    Stream
    Event

cuda_core/docs/source/api_private.rst

@@ -22,14 +22,17 @@ CUDA runtime
    _memory._virtual_memory_resource.VirtualMemoryGranularityT
    _memory._virtual_memory_resource.VirtualMemoryAccessTypeT
    _memory._virtual_memory_resource.VirtualMemoryHandleTypeT
-   _device.DeviceProperties
-   _memory._ipc.IPCAllocationHandle
-   _memory._ipc.IPCBufferDescriptor
    _module.KernelAttributes
    _module.KernelOccupancy
    _module.ParamInfo
    _module.MaxPotentialBlockSizeOccupancyResult
 
+   :template: autosummary/cyclass.rst
+
+   _device.DeviceProperties
+   _memory._ipc.IPCAllocationHandle
+   _memory._ipc.IPCBufferDescriptor
+
 
 CUDA protocols
 --------------

cuda_core/docs/source/conf.py

@@ -51,6 +51,12 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
+# Include object entries (methods, attributes, etc.) in the table of contents
+# This enables the "On This Page" sidebar to show class methods and properties
+# Requires Sphinx 5.1+
+toc_object_entries = True
+toc_object_entries_show_parents = "domain"
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -67,6 +73,10 @@
         "version-switcher",
         "navbar-nav",
     ],
+    # Use custom secondary sidebar that includes autodoc entries
+    "secondary_sidebar_items": ["page-toc"],
+    # Show more TOC levels by default
+    "show_toc_level": 3,
 }
 if os.environ.get("CI"):
     if int(os.environ.get("BUILD_PREVIEW", 0)):

cuda_pathfinder/docs/source/conf.py

@@ -54,6 +54,12 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
+# Include object entries (methods, attributes, etc.) in the table of contents
+# This enables the "On This Page" sidebar to show class methods and properties
+# Requires Sphinx 5.1+
+toc_object_entries = True
+toc_object_entries_show_parents = "domain"
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -70,6 +76,10 @@
         "version-switcher",
         "navbar-nav",
     ],
+    # Use custom secondary sidebar that includes autodoc entries
+    "secondary_sidebar_items": ["page-toc"],
+    # Show more TOC levels by default
+    "show_toc_level": 3,
 }
 if os.environ.get("CI"):
     if int(os.environ.get("BUILD_PREVIEW", 0)):

cuda_python/docs/source/conf.py

@@ -47,6 +47,12 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
+# Include object entries (methods, attributes, etc.) in the table of contents
+# This enables the "On This Page" sidebar to show class methods and properties
+# Requires Sphinx 5.1+
+toc_object_entries = True
+toc_object_entries_show_parents = "domain"
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -63,6 +69,10 @@
         "version-switcher",
         "navbar-nav",
     ],
+    # Use custom secondary sidebar that includes autodoc entries
+    "secondary_sidebar_items": ["page-toc"],
+    # Show more TOC levels by default
+    "show_toc_level": 3,
 }
 if os.environ.get("CI"):
     if int(os.environ.get("BUILD_PREVIEW", 0)):