Add API docs for cuda.core.graph and fix stale docstring references

The _graph -> graph rename left behind broken Sphinx cross-references
and the new graph types were missing from the API reference.

Made-with: Cursor

Author: Andy-Jost

cuda_core/cuda/core/_launcher.pyx

@@ -26,7 +26,7 @@ def launch(stream: Stream | GraphBuilder | IsStreamT, config: LaunchConfig, kern
 
     Parameters
     ----------
-    stream : :obj:`~_stream.Stream` | :obj:`~_graph.GraphBuilder`
+    stream : :obj:`~_stream.Stream` | :obj:`~graph.GraphBuilder`
         The stream establishing the stream ordering semantic of a
         launch.
     config : :obj:`LaunchConfig`

cuda_core/cuda/core/_memory/_buffer.pyx

@@ -182,7 +182,7 @@ cdef class Buffer:
 
         Parameters
         ----------
-        stream : :obj:`~_stream.Stream` | :obj:`~_graph.GraphBuilder`, optional
+        stream : :obj:`~_stream.Stream` | :obj:`~graph.GraphBuilder`, optional
             The stream object to use for asynchronous deallocation. If None,
             the deallocation stream stored in the handle is used.
         """
@@ -206,7 +206,7 @@ cdef class Buffer:
         ----------
         dst : :obj:`~_memory.Buffer`
             Source buffer to copy data from
-        stream : :obj:`~_stream.Stream` | :obj:`~_graph.GraphBuilder`
+        stream : :obj:`~_stream.Stream` | :obj:`~graph.GraphBuilder`
             Keyword argument specifying the stream for the
             asynchronous copy
 
@@ -237,7 +237,7 @@ cdef class Buffer:
         ----------
         src : :obj:`~_memory.Buffer`
             Source buffer to copy data from
-        stream : :obj:`~_stream.Stream` | :obj:`~_graph.GraphBuilder`
+        stream : :obj:`~_stream.Stream` | :obj:`~graph.GraphBuilder`
             Keyword argument specifying the stream for the
             asynchronous copy
 
@@ -262,7 +262,7 @@ cdef class Buffer:
         value : int | :obj:`collections.abc.Buffer`
             - int: Must be in range [0, 256). Converted to 1 byte.
             - :obj:`collections.abc.Buffer`: Must be 1, 2, or 4 bytes.
-        stream : :obj:`~_stream.Stream` | :obj:`~_graph.GraphBuilder`
+        stream : :obj:`~_stream.Stream` | :obj:`~graph.GraphBuilder`
             Stream for the asynchronous fill operation.
 
         Raises
@@ -496,7 +496,7 @@ cdef class MemoryResource:
         ----------
         size : int
             The size of the buffer to allocate, in bytes.
-        stream : :obj:`~_stream.Stream` | :obj:`~_graph.GraphBuilder`, optional
+        stream : :obj:`~_stream.Stream` | :obj:`~graph.GraphBuilder`, optional
             The stream on which to perform the allocation asynchronously.
             If None, it is up to each memory resource implementation to decide
             and document the behavior.
@@ -518,7 +518,7 @@ cdef class MemoryResource:
             The pointer or handle to the buffer to deallocate.
         size : int
             The size of the buffer to deallocate, in bytes.
-        stream : :obj:`~_stream.Stream` | :obj:`~_graph.GraphBuilder`, optional
+        stream : :obj:`~_stream.Stream` | :obj:`~graph.GraphBuilder`, optional
             The stream on which to perform the deallocation asynchronously.
             If None, it is up to each memory resource implementation to decide
             and document the behavior.

cuda_core/cuda/core/_memory/_memory_pool.pyx

@@ -129,7 +129,7 @@ cdef class _MemPool(MemoryResource):
         ----------
         size : int
             The size of the buffer to allocate, in bytes.
-        stream : :obj:`~_stream.Stream` | :obj:`~_graph.GraphBuilder`, optional
+        stream : :obj:`~_stream.Stream` | :obj:`~graph.GraphBuilder`, optional
             The stream on which to perform the allocation asynchronously.
             If None, an internal stream is used.
 
@@ -153,7 +153,7 @@ cdef class _MemPool(MemoryResource):
             The pointer or handle to the buffer to deallocate.
         size : int
             The size of the buffer to deallocate, in bytes.
-        stream : :obj:`~_stream.Stream` | :obj:`~_graph.GraphBuilder`, optional
+        stream : :obj:`~_stream.Stream` | :obj:`~graph.GraphBuilder`, optional
             The stream on which to perform the deallocation asynchronously.
             If the buffer is deallocated without an explicit stream, the allocation stream
             is used.

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()`
+    """Customizable options for :obj:`~graph.GraphBuilder.debug_dot_print()`
 
     Attributes
     ----------
@@ -119,7 +119,7 @@ class GraphDebugPrintOptions:
 
 @dataclass
 class GraphCompleteOptions:
-    """Customizable options for :obj:`_graph.GraphBuilder.complete()`
+    """Customizable options for :obj:`~graph.GraphBuilder.complete()`
 
     Attributes
     ----------
@@ -188,7 +188,7 @@ class GraphBuilder:
     them with a specified dependency tree. It speeds up the workflow by combining the
     driver activities associated with CUDA kernel launches and CUDA API calls.
 
-    Directly creating a :obj:`~_graph.GraphBuilder` is not supported due
+    Directly creating a :obj:`~graph.GraphBuilder` is not supported due
     to ambiguity. New graph builders should instead be created through a
     :obj:`~_device.Device`, or a :obj:`~_stream.stream` object.
 
@@ -326,16 +326,16 @@ class GraphBuilder:
         return self
 
     def complete(self, options: GraphCompleteOptions | None = None) -> "Graph":
-        """Completes the graph builder and returns the built :obj:`~_graph.Graph` object.
+        """Completes the graph builder and returns the built :obj:`~graph.Graph` object.
 
         Parameters
         ----------
-        options : :obj:`~_graph.GraphCompleteOptions`, optional
+        options : :obj:`~graph.GraphCompleteOptions`, optional
             Customizable dataclass for the graph builder completion options.
 
         Returns
         -------
-        graph : :obj:`~_graph.Graph`
+        graph : :obj:`~graph.Graph`
             The newly built graph.
 
         """
@@ -351,7 +351,7 @@ class GraphBuilder:
         ----------
         path : str
             File path to use for writting debug DOT output
-        options : :obj:`~_graph.GraphDebugPrintOptions`, optional
+        options : :obj:`~graph.GraphDebugPrintOptions`, optional
             Customizable dataclass for the debug print options.
 
         """
@@ -373,7 +373,7 @@ class GraphBuilder:
 
         Returns
         -------
-        graph_builders : tuple[:obj:`~_graph.GraphBuilder`, ...]
+        graph_builders : tuple[:obj:`~graph.GraphBuilder`, ...]
             A tuple of split graph builders. The first graph builder in the tuple
             is always the original graph builder.
 
@@ -400,12 +400,12 @@ class GraphBuilder:
 
         Parameters
         ----------
-        *graph_builders : :obj:`~_graph.GraphBuilder`
+        *graph_builders : :obj:`~graph.GraphBuilder`
             The graph builders to join.
 
         Returns
         -------
-        graph_builder : :obj:`~_graph.GraphBuilder`
+        graph_builder : :obj:`~graph.GraphBuilder`
             The newly joined graph builder.
 
         """
@@ -521,7 +521,7 @@ class GraphBuilder:
 
         Returns
         -------
-        graph_builder : :obj:`~_graph.GraphBuilder`
+        graph_builder : :obj:`~graph.GraphBuilder`
             The newly created conditional graph builder.
 
         """
@@ -552,7 +552,7 @@ class GraphBuilder:
 
         Returns
         -------
-        graph_builders : tuple[:obj:`~_graph.GraphBuilder`, :obj:`~_graph.GraphBuilder`]
+        graph_builders : tuple[:obj:`~graph.GraphBuilder`, :obj:`~graph.GraphBuilder`]
             A tuple of two new graph builders, one for the if branch and one for the else branch.
 
         """
@@ -586,7 +586,7 @@ class GraphBuilder:
 
         Returns
         -------
-        graph_builders : tuple[:obj:`~_graph.GraphBuilder`, ...]
+        graph_builders : tuple[:obj:`~graph.GraphBuilder`, ...]
             A tuple of new graph builders, one for each branch.
 
         """
@@ -617,7 +617,7 @@ class GraphBuilder:
 
         Returns
         -------
-        graph_builder : :obj:`~_graph.GraphBuilder`
+        graph_builder : :obj:`~graph.GraphBuilder`
             The newly created while loop graph builder.
 
         """
@@ -643,13 +643,13 @@ class GraphBuilder:
         self._mnff.close()
 
     def add_child(self, child_graph: GraphBuilder):
-        """Adds the child :obj:`~_graph.GraphBuilder` builder into self.
+        """Adds the child :obj:`~graph.GraphBuilder` builder into self.
 
         The child graph builder will be added as a child node to the parent graph builder.
 
         Parameters
         ----------
-        child_graph : :obj:`~_graph.GraphBuilder`
+        child_graph : :obj:`~graph.GraphBuilder`
             The child graph builder. Must have finished building.
         """
         if not child_graph._building_ended:
@@ -743,7 +743,7 @@ class Graph:
     them with a specified dependency tree. It speeds up the workflow by combining the
     driver activities associated with CUDA kernel launches and CUDA API calls.
 
-    Graphs must be built using a :obj:`~_graph.GraphBuilder` object.
+    Graphs must be built using a :obj:`~graph.GraphBuilder` object.
 
     """
 

cuda_core/cuda/core/graph/_graph_def.pyx

@@ -278,7 +278,7 @@ cdef class GraphDef:
 
         Parameters
         ----------
-        options : :obj:`~_graph.GraphCompleteOptions`, optional
+        options : :obj:`~graph.GraphCompleteOptions`, optional
             Customizable dataclass for graph instantiation options.
 
         Returns

cuda_core/docs/source/api.rst

@@ -20,8 +20,6 @@ CUDA runtime
    :toctree: generated/
 
    Device
-   Graph
-   GraphBuilder
    launch
 
    :template: autosummary/cyclass.rst
@@ -43,8 +41,6 @@ CUDA runtime
    PinnedMemoryResourceOptions
    ManagedMemoryResourceOptions
    EventOptions
-   GraphCompleteOptions
-   GraphDebugPrintOptions
    StreamOptions
    LaunchConfig
    VirtualMemoryResourceOptions
@@ -62,6 +58,52 @@ CUDA runtime
    on other non-blocking streams.
 
 
+CUDA graphs
+-----------
+
+.. autosummary::
+   :toctree: generated/
+
+   graph.Graph
+   graph.GraphBuilder
+   graph.GraphDef
+
+   :template: autosummary/cyclass.rst
+
+   graph.GraphNode
+   graph.Condition
+
+   :template: dataclass.rst
+
+   graph.GraphAllocOptions
+   graph.GraphCompleteOptions
+   graph.GraphDebugPrintOptions
+
+Node types
+``````````
+
+.. autosummary::
+   :toctree: generated/
+
+   :template: autosummary/cyclass.rst
+
+   graph.EmptyNode
+   graph.KernelNode
+   graph.AllocNode
+   graph.FreeNode
+   graph.MemsetNode
+   graph.MemcpyNode
+   graph.ChildGraphNode
+   graph.EventRecordNode
+   graph.EventWaitNode
+   graph.HostCallbackNode
+   graph.ConditionalNode
+   graph.IfNode
+   graph.IfElseNode
+   graph.WhileNode
+   graph.SwitchNode
+
+
 CUDA compilation toolchain
 --------------------------
 

cuda_core/docs/source/api_private.rst

@@ -34,6 +34,15 @@ CUDA runtime
    _memory._ipc.IPCBufferDescriptor
 
 
+CUDA graphs
+-----------
+
+.. autosummary::
+   :toctree: generated/
+
+   graph._adjacency_set_proxy.AdjacencySetProxy
+
+
 CUDA protocols
 --------------