Fix documentation: DeviceProperties display and sidebar navigation #1444
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Contributor
|
Auto-sync is disabled for ready for review pull requests in this repository. Workflows must be run manually. Contributors can view more details about this message here. |
Collaborator
Author
|
/ok to test |
This comment has been minimized.
This comment has been minimized.
kkraus14
force-pushed
the
fix-device-properties-docs
branch
from
28a91ab to
13292b1
Compare
Collaborator
Author
|
/ok to test |
Contributor
|
Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually. Contributors can view more details about this message here. |
kkraus14
changed the title
Collaborator
Author
|
/ok to test |
kkraus14
force-pushed
the
fix-device-properties-docs
branch
2 times, most recently
from
50b6537 to
18fe7df
Compare
Collaborator
Author
|
/ok to test |
1 similar comment
Collaborator
Author
|
/ok to test |
kkraus14
force-pushed
the
fix-device-properties-docs
branch
from
14b4c8b to
b2d165f
Compare
Collaborator
Author
|
/ok to test |
7 similar comments
Collaborator
Author
|
/ok to test |
Collaborator
Author
|
/ok to test |
Collaborator
Author
|
/ok to test |
Collaborator
Author
|
/ok to test |
Collaborator
Author
|
/ok to test |
Collaborator
Author
|
/ok to test |
Collaborator
Author
|
/ok to test |
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 NVIDIA#1215
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 NVIDIA#1100
…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 NVIDIA#1100
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.
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.
- 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.
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)
- 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
- Device, Graph, GraphBuilder are regular Python classes (use default) - LaunchConfig uses dataclass template per project convention
kkraus14
force-pushed
the
fix-device-properties-docs
branch
from
1c7cb4a to
0ad1a8a
Compare
rparolin
approved these changes
Jan 9, 2026
Collaborator
Author
|
/ok to test |
|
Collaborator
Author
|
Should probably backport the toc level fixes here to |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR addresses two documentation issues:
Fix Cython class documentation (Fixes #1215)
Cython
cdef classtypes and Python classes inheriting from them were not being documented correctly. Thecyclass.rsttemplate usesautoattributeinstead ofautopropertybecause Cython extension types don't expose their properties the same way as pure Python classes.Enable class members in sidebar navigation (Fixes #1100)
The "On This Page" sidebar was not showing class methods and attributes. Fixed with multiple configuration changes.
Changes
1. Sphinx TOC configuration (
conf.pyfiles)toc_object_entries = True- Sphinx 5.1+ option to add object descriptions to TOCtoc_object_entries_show_parents = "domain"- Shows class-prefixed names in sidebar"show_toc_level": 3- pydata-sphinx-theme option to show more TOC levels"secondary_sidebar_items": ["page-toc"]- Explicit secondary sidebar configuration2. Template assignments
Applied
cyclass.rsttemplate to all Cythoncdef classtypes and Python classes that inherit from them:Buffer,Stream,Event,MemoryResource,DeviceMemoryResource,GraphMemoryResource,PinnedMemoryResource,ManagedMemoryResource,LegacyPinnedMemoryResource,VirtualMemoryResource,DeviceProperties,IPCAllocationHandle,IPCBufferDescriptor,system.Device,StridedMemoryViewDeviceMemoryResourceOptions,PinnedMemoryResourceOptions,ManagedMemoryResourceOptions,EventOptions,StreamOptions,LaunchConfig,GraphCompleteOptions,GraphDebugPrintOptions,VirtualMemoryResourceOptionsDevice,Graph,GraphBuilder,Kernel,ObjectCode,Program,Linker, etc.3. Template improvements
cyclass.rst: Added.. rubric:: Attributesheader for consistency with Methods sectioncyclass.rst: Reordered to list Methods before Attributes (matchingclass.rst)Result