Update docstrings, api.rst structure, and release notes

- Rename "Memory" section to "Memory management" in api.rst
- Add introductory paragraph under "Node types" subsection
- Update node docstrings to concise noun phrases
- Update graph API class docstrings (GraphBuilder, Graph, etc.)
- Revise release notes highlights and new features sections
- Fix test_registry_cleanup import path (cuda.core._graph -> cuda.core.graph)

Made-with: Cursor

Author: Andy-Jost

cuda_core/cuda/core/graph/_graph_builder.pyx

@@ -23,7 +23,7 @@ from cuda.core._utils.cuda_utils import (
 
 @dataclass
 class GraphDebugPrintOptions:
-    """Customizable options for :obj:`~graph.GraphBuilder.debug_dot_print()`
+    """Options for debug_dot_print().
 
     Attributes
     ----------
@@ -119,7 +119,7 @@ class GraphDebugPrintOptions:
 
 @dataclass
 class GraphCompleteOptions:
-    """Customizable options for :obj:`~graph.GraphBuilder.complete()`
+    """Options for graph instantiation.
 
     Attributes
     ----------
@@ -182,7 +182,7 @@ def _instantiate_graph(h_graph, options: GraphCompleteOptions | None = None) ->
 
 
 class GraphBuilder:
-    """Represents a graph under construction.
+    """A graph under construction by stream capture.
 
     A graph groups a set of CUDA kernels and other CUDA operations together and executes
     them with a specified dependency tree. It speeds up the workflow by combining the
@@ -737,7 +737,7 @@ class GraphBuilder:
 
 
 class Graph:
-    """Represents an executable graph.
+    """An executable graph.
 
     A graph groups a set of CUDA kernels and other CUDA operations together and executes
     them with a specified dependency tree. It speeds up the workflow by combining the

cuda_core/cuda/core/graph/_graph_def.pyx

@@ -30,7 +30,7 @@ from cuda.core._utils.cuda_utils import driver, handle_return
 
 
 cdef class Condition:
-    """Wraps a CUgraphConditionalHandle.
+    """A condition variable for conditional graph nodes.
 
     Created by :meth:`GraphDef.create_condition` and passed to
     conditional-node builder methods (``if_cond``, ``if_else``,
@@ -92,7 +92,7 @@ class GraphAllocOptions:
 
 
 cdef class GraphDef:
-    """Represents a CUDA graph definition (CUgraph).
+    """A graph definition.
 
     A GraphDef is used to construct a graph explicitly by adding nodes
     and specifying dependencies. Once construction is complete, call

cuda_core/cuda/core/graph/_graph_node.pyx

@@ -73,7 +73,7 @@ cdef inline GraphNode _registered(GraphNode n):
 
 
 cdef class GraphNode:
-    """Base class for all graph nodes.
+    """A node in a graph definition.
 
     Nodes are created by calling builder methods on GraphDef (for
     entry-point nodes with no dependencies) or on other Nodes (for

cuda_core/cuda/core/graph/_subclasses.pyx

@@ -49,7 +49,7 @@ cdef bint _check_node_get_params():
 
 
 cdef class EmptyNode(GraphNode):
-    """A synchronization / join node with no operation."""
+    """An empty (synchronization) node."""
 
     @staticmethod
     cdef EmptyNode _create_impl(GraphNodeHandle h_node):
@@ -247,7 +247,7 @@ cdef class AllocNode(GraphNode):
 
 
 cdef class FreeNode(GraphNode):
-    """A memory free node.
+    """A memory deallocation node.
 
     Properties
     ----------
@@ -283,7 +283,7 @@ cdef class FreeNode(GraphNode):
 
 
 cdef class MemsetNode(GraphNode):
-    """A memory set node.
+    """A memset node.
 
     Properties
     ----------
@@ -364,7 +364,7 @@ cdef class MemsetNode(GraphNode):
 
 
 cdef class MemcpyNode(GraphNode):
-    """A memory copy node.
+    """A memcpy node.
 
     Properties
     ----------
@@ -437,7 +437,7 @@ cdef class MemcpyNode(GraphNode):
 
 
 cdef class ChildGraphNode(GraphNode):
-    """A child graph (sub-graph) node.
+    """A child graph node.
 
     Properties
     ----------
@@ -602,7 +602,7 @@ cdef class HostCallbackNode(GraphNode):
 
 
 cdef class ConditionalNode(GraphNode):
-    """Base class for conditional graph nodes.
+    """Base class for conditional nodes.
 
     When created via builder methods (if_cond, if_else, while_loop, switch),
     a specific subclass (IfNode, IfElseNode, WhileNode, SwitchNode) is
@@ -707,7 +707,7 @@ cdef class ConditionalNode(GraphNode):
 
 
 cdef class IfNode(ConditionalNode):
-    """An if-conditional node (1 branch, executes when condition is non-zero)."""
+    """An if-conditional node."""
 
     def __repr__(self) -> str:
         return (f"<IfNode handle=0x{as_intptr(self._h_node):x}"
@@ -720,7 +720,7 @@ cdef class IfNode(ConditionalNode):
 
 
 cdef class IfElseNode(ConditionalNode):
-    """An if-else conditional node (2 branches)."""
+    """An if-else conditional node."""
 
     def __repr__(self) -> str:
         return (f"<IfElseNode handle=0x{as_intptr(self._h_node):x}"
@@ -738,7 +738,7 @@ cdef class IfElseNode(ConditionalNode):
 
 
 cdef class WhileNode(ConditionalNode):
-    """A while-loop conditional node (1 branch, repeats while condition is non-zero)."""
+    """A while-loop conditional node."""
 
     def __repr__(self) -> str:
         return (f"<WhileNode handle=0x{as_intptr(self._h_node):x}"
@@ -751,7 +751,7 @@ cdef class WhileNode(ConditionalNode):
 
 
 cdef class SwitchNode(ConditionalNode):
-    """A switch conditional node (N branches, selected by condition value)."""
+    """A switch conditional node."""
 
     def __repr__(self) -> str:
         return (f"<SwitchNode handle=0x{as_intptr(self._h_node):x}"

cuda_core/docs/source/api.rst

@@ -13,8 +13,8 @@ be considered stable and will follow semantic versioning with appropriate
 deprecation periods for breaking changes.
 
 
-CUDA runtime
-------------
+Devices and execution
+---------------------
 
 .. autosummary::
    :toctree: generated/
@@ -24,26 +24,14 @@ CUDA runtime
 
    :template: autosummary/cyclass.rst
 
-   Buffer
    Stream
    Event
-   MemoryResource
-   DeviceMemoryResource
-   GraphMemoryResource
-   PinnedMemoryResource
-   ManagedMemoryResource
-   LegacyPinnedMemoryResource
-   VirtualMemoryResource
 
    :template: dataclass.rst
 
-   DeviceMemoryResourceOptions
-   PinnedMemoryResourceOptions
-   ManagedMemoryResourceOptions
-   EventOptions
    StreamOptions
+   EventOptions
    LaunchConfig
-   VirtualMemoryResourceOptions
 
 .. data:: LEGACY_DEFAULT_STREAM
 
@@ -58,9 +46,42 @@ CUDA runtime
    on other non-blocking streams.
 
 
+Memory management
+-----------------
+
+.. autosummary::
+   :toctree: generated/
+
+   :template: autosummary/cyclass.rst
+
+   Buffer
+   MemoryResource
+   DeviceMemoryResource
+   GraphMemoryResource
+   PinnedMemoryResource
+   ManagedMemoryResource
+   LegacyPinnedMemoryResource
+   VirtualMemoryResource
+
+   :template: dataclass.rst
+
+   DeviceMemoryResourceOptions
+   PinnedMemoryResourceOptions
+   ManagedMemoryResourceOptions
+   VirtualMemoryResourceOptions
+
+
 CUDA graphs
 -----------
 
+A CUDA graph captures a set of GPU operations and their dependencies,
+allowing them to be defined once and launched repeatedly with minimal
+CPU overhead. Graphs can be constructed in two ways:
+:class:`~graph.GraphBuilder` captures operations from a stream, while
+:class:`~graph.GraphDef` builds a graph explicitly by adding nodes and
+edges. Both produce an executable :class:`~graph.Graph` that can be
+launched on a :class:`Stream`.
+
 .. autosummary::
    :toctree: generated/
 
@@ -82,6 +103,10 @@ CUDA graphs
 Node types
 ``````````
 
+Every graph node is a subclass of :class:`~graph.GraphNode`, which
+provides the common interface (dependencies, successors, destruction).
+Each subclass exposes attributes unique to its operation type.
+
 .. autosummary::
    :toctree: generated/
 

cuda_core/docs/source/release/0.7.x-notes.rst

@@ -10,23 +10,14 @@
 Highlights
 ----------
 
-- Introduced :class:`~graph.GraphDef`, an explicit graph construction API. Graphs
-  can now be built node-by-node (kernel launches, memset, memcpy, memory
-  allocation/free, child graphs, event record/wait, host callbacks, and
-  conditionals) with full control over topology. Nodes expose mutable
-  :attr:`~graph.GraphNode.pred` and :attr:`~graph.GraphNode.succ` adjacency sets
-  for edge manipulation, and individual nodes can be destroyed with
-  :meth:`~graph.GraphNode.destroy`. A ``GraphDef`` can be instantiated into an
-  executable :class:`Graph` or used to update an existing one in place.
+- Introduced support for explicit graph construction. CUDA graphs can now be
+  built programmatically by adding nodes and edges, and their topology can be
+  modified after construction.
 
 
 Breaking Changes
 ----------------
 
-- The internal ``cuda.core._graph`` package has been renamed to the public
-  :mod:`cuda.core.graph`. Code that imported from ``cuda.core._graph`` must
-  update its import paths.
-
 - Building ``cuda.core`` from source now requires ``cuda-bindings`` >= 12.9.0, due to Cython-level
   dependencies on the NVVM and nvJitLink bindings (``cynvvm``, ``cynvjitlink``). Pre-built wheels
   are unaffected. The previous minimum was 12.8.0.
@@ -35,13 +26,10 @@ Breaking Changes
 New features
 ------------
 
-- Added the :mod:`cuda.core.graph` public module containing :class:`~graph.GraphDef`,
-  :class:`~graph.GraphNode`, :class:`~graph.Condition`, :class:`~graph.GraphAllocOptions`,
-  and typed node subclasses (:class:`~graph.KernelNode`, :class:`~graph.MemsetNode`,
-  :class:`~graph.MemcpyNode`, :class:`~graph.AllocNode`, :class:`~graph.FreeNode`,
-  :class:`~graph.EmptyNode`, :class:`~graph.ChildGraphNode`,
-  :class:`~graph.EventRecordNode`, :class:`~graph.EventWaitNode`,
-  :class:`~graph.HostCallbackNode`, and conditional node types).
+- Added the :mod:`cuda.core.graph` public module containing
+  :class:`~graph.GraphDef` for explicit graph construction, typed node
+  subclasses, and supporting types. :class:`~graph.GraphBuilder` (stream
+  capture) also moves into this module.
 
 - Added ``preferred_location_type`` option to :class:`ManagedMemoryResourceOptions`
   for explicit control over the preferred location kind (``"device"``,

cuda_core/tests/graph/test_graphdef.py

@@ -729,7 +729,7 @@ def test_registry_cleanup(init_cuda):
     """Node registry entries are removed on destroy() and graph teardown."""
     import gc
 
-    from cuda.core._graph._graph_def._graph_node import _node_registry
+    from cuda.core.graph._graph_node import _node_registry
 
     def registered(node):
         return any(v is node for v in _node_registry.values())