Merge pull request #258 from ksimpson-work/link_doc_references

Make the link to different object types explicit for the docs

Author: leofang

cuda_core/cuda/core/experimental/_device.py

@@ -23,11 +23,11 @@ class Device:
     and use the same GPU device.
 
     While acting as the entry point, many other CUDA resources can be
-    allocated such as streams and buffers. Any :obj:`Context` dependent
+    allocated such as streams and buffers. Any :obj:`~_context.Context` dependent
     resource created through this device, will continue to refer to
     this device's context.
 
-    Newly returend :obj:`Device` object are is a thread-local singleton
+    Newly returned :obj:`~_device.Device` objects are thread-local singletons
     for a specified device.
 
     Note
@@ -37,7 +37,7 @@ class Device:
     Parameters
     ----------
     device_id : int, optional
-        Device ordinal to return a :obj:`Device` object for.
+        Device ordinal to return a :obj:`~_device.Device` object for.
         Default value of `None` return the currently used device.
 
     """
@@ -144,7 +144,7 @@ def compute_capability(self) -> ComputeCapability:
     @property
     @precondition(_check_context_initialized)
     def context(self) -> Context:
-        """Return the current :obj:`Context` associated with this device.
+        """Return the current :obj:`~_context.Context` associated with this device.
 
         Note
         ----
@@ -157,7 +157,7 @@ def context(self) -> Context:
 
     @property
     def memory_resource(self) -> MemoryResource:
-        """Return :obj:`MemoryResource` associated with this device."""
+        """Return :obj:`~_memory.MemoryResource` associated with this device."""
         return self._mr
 
     @memory_resource.setter
@@ -168,7 +168,7 @@ def memory_resource(self, mr):
 
     @property
     def default_stream(self) -> Stream:
-        """Return default CUDA :obj:`Stream` associated with this device.
+        """Return default CUDA :obj:`~_stream.Stream` associated with this device.
 
         The type of default stream returned depends on if the environment
         variable CUDA_PYTHON_CUDA_PER_THREAD_DEFAULT_STREAM is set.
@@ -191,18 +191,18 @@ def set_current(self, ctx: Context = None) -> Union[Context, None]:
 
         Initializes CUDA and sets the calling thread to a valid CUDA
         context. By default the primary context is used, but optional `ctx`
-        parameter can be used to explicitly supply a :obj:`Context` object.
+        parameter can be used to explicitly supply a :obj:`~_context.Context` object.
 
         Providing a `ctx` causes the previous set context to be popped and returned.
 
         Parameters
         ----------
-        ctx : :obj:`Context`, optional
+        ctx : :obj:`~_context.Context`, optional
             Optional context to push onto this device's current thread stack.
 
         Returns
         -------
-        Union[:obj:`Context`, None], optional
+        Union[:obj:`~_context.Context`, None], optional
             Popped context.
 
         Examples
@@ -247,20 +247,20 @@ def set_current(self, ctx: Context = None) -> Union[Context, None]:
             self._has_inited = True
 
     def create_context(self, options: ContextOptions = None) -> Context:
-        """Create a new :obj:`Context` object.
+        """Create a new :obj:`~_context.Context` object.
 
         Note
         ----
         The newly context will not be set as current.
 
         Parameters
         ----------
-        options : :obj:`ContextOptions`, optional
+        options : :obj:`~_context.ContextOptions`, optional
             Customizable dataclass for context creation options.
 
         Returns
         -------
-        :obj:`Context`
+        :obj:`~_context.Context`
             Newly created context object.
 
         """
@@ -286,12 +286,12 @@ def create_stream(self, obj=None, options: StreamOptions = None) -> Stream:
         ----------
         obj : Any, optional
             Any object supporting the __cuda_stream__ protocol.
-        options : :obj:`StreamOptions`, optional
+        options : :obj:`~_stream.StreamOptions`, optional
             Customizable dataclass for stream creation options.
 
         Returns
         -------
-        :obj:`Stream`
+        :obj:`~_stream.Stream`
             Newly created stream object.
 
         """
@@ -314,13 +314,13 @@ def allocate(self, size, stream=None) -> Buffer:
         ----------
         size : int
             Number of bytes to allocate.
-        stream : :obj:`Stream`, optional
+        stream : :obj:`~_stream.Stream`, optional
             The stream establishing the stream ordering semantic.
             Default value of `None` uses default stream.
 
         Returns
         -------
-        :obj:`Buffer`
+        :obj:`~_memory.Buffer`
             Newly created buffer object.
 
         """

cuda_core/cuda/core/experimental/_event.py

@@ -12,7 +12,7 @@
 
 @dataclass
 class EventOptions:
-    """Customizable :obj:`Event` options.
+    """Customizable :obj:`~_event.Event` options.
 
     Attributes
     ----------
@@ -46,8 +46,8 @@ class Event:
     of work up to event's record, and help establish dependencies
     between GPU work submissions.
 
-    Directly creating an :obj:`Event` is not supported due to ambiguity,
-    and they should instead be created through a :obj:`Stream` object.
+    Directly creating an :obj:`~_event.Event` is not supported due to ambiguity,
+    and they should instead be created through a :obj:`~_stream.Stream` object.
 
     """
 

cuda_core/cuda/core/experimental/_launcher.py

@@ -47,7 +47,7 @@ class LaunchConfig:
         Group of threads (Thread Block) that will execute on the same
         streaming multiprocessor (SM). Threads within a thread blocks have
         access to shared memory and can be explicitly synchronized.
-    stream : :obj:`Stream`
+    stream : :obj:`~_stream.Stream`
         The stream establishing the stream ordering semantic of a
         launch.
     shmem_size : int, optional
@@ -108,16 +108,16 @@ def _cast_to_3_tuple(self, cfg):
 
 
 def launch(kernel, config, *kernel_args):
-    """Launches a :obj:`~cuda.core.experimental._module.Kernel`
+    """Launches a :obj:`~_module.Kernel`
     object with launch-time configuration.
 
     Parameters
     ----------
-    kernel : :obj:`~cuda.core.experimental._module.Kernel`
+    kernel : :obj:`~_module.Kernel`
         Kernel to launch.
-    config : :obj:`LaunchConfig`
+    config : :obj:`~_launcher.LaunchConfig`
         Launch configurations inline with options provided by
-        :obj:`LaunchConfig` dataclass.
+        :obj:`~_launcher.LaunchConfig` dataclass.
     *kernel_args : Any
         Variable length argument list that is provided to the
         launching kernel.

cuda_core/cuda/core/experimental/_memory.py

@@ -37,7 +37,7 @@ class Buffer:
         Allocated buffer handle object
     size : Any
         Memory size of the buffer
-    mr : :obj:`MemoryResource`, optional
+    mr : :obj:`~_memory.MemoryResource`, optional
         Memory resource associated with the buffer
 
     """
@@ -126,7 +126,7 @@ def copy_to(self, dst: Buffer = None, *, stream) -> Buffer:
 
         Parameters
         ----------
-        dst : :obj:`Buffer`
+        dst : :obj:`~_memory.Buffer`
             Source buffer to copy data from
         stream : Any
             Keyword argument specifying the stream for the
@@ -149,7 +149,7 @@ def copy_from(self, src: Buffer, *, stream):
 
         Parameters
         ----------
-        src : :obj:`Buffer`
+        src : :obj:`~_memory.Buffer`
             Source buffer to copy data from
         stream : Any
             Keyword argument specifying the stream for the

cuda_core/cuda/core/experimental/_module.py

@@ -48,10 +48,10 @@ class Kernel:
     """Represent a compiled kernel that had been loaded onto the device.
 
     Kernel instances can execution when passed directly into the
-    :func:`~cuda.core.experimental.launch` function.
+    :func:`~launch` function.
 
-    Directly creating a :obj:`Kernel` is not supported, and they
-    should instead be created through a :obj:`ObjectCode` object.
+    Directly creating a :obj:`~_module.Kernel` is not supported, and they
+    should instead be created through a :obj:`~_module.ObjectCode` object.
 
     """
 
@@ -164,7 +164,7 @@ def _lazy_load_module(self, *args, **kwargs):
 
     @precondition(_lazy_load_module)
     def get_kernel(self, name):
-        """Return the :obj:`Kernel` of a specified name from this object code.
+        """Return the :obj:`~_module.Kernel` of a specified name from this object code.
 
         Parameters
         ----------
@@ -173,7 +173,7 @@ def get_kernel(self, name):
 
         Returns
         -------
-        :obj:`Kernel`
+        :obj:`~_module.Kernel`
             Newly created kernel object.
 
         """

cuda_core/cuda/core/experimental/_program.py

@@ -11,7 +11,7 @@
 
 class Program:
     """Represent a compilation machinery to process programs into
-    :obj:`~cuda.core.experimental._module.ObjectCode`.
+    :obj:`~_module.ObjectCode`.
 
     This object provides a unified interface to multiple underlying
     compiler libraries. Compilation support is enabled for a wide
@@ -72,7 +72,7 @@ def compile(self, target_type, options=(), name_expressions=(), logs=None):
             Supported options are "ptx", "cubin" and "ltoir".
         options : Union[List, Tuple], optional
             List of compilation options associated with the backend
-            of this :obj:`Program`. (Default to no options)
+            of this :obj:`~_program.Program`. (Default to no options)
         name_expressions : Union[List, Tuple], optional
             List of explicit name expressions to become accessible.
             (Default to no expressions)
@@ -83,7 +83,7 @@ def compile(self, target_type, options=(), name_expressions=(), logs=None):
 
         Returns
         -------
-        :obj:`~cuda.core.experimental._module.ObjectCode`
+        :obj:`~_module.ObjectCode`
             Newly created code object.
 
         """

cuda_core/cuda/core/experimental/_stream.py

@@ -19,7 +19,7 @@
 
 @dataclass
 class StreamOptions:
-    """Customizable :obj:`Stream` options.
+    """Customizable :obj:`~_stream.Stream` options.
 
     Attributes
     ----------
@@ -41,13 +41,13 @@ class Stream:
     Applications use streams to control the order of execution for
     GPU work. Work within a single stream are executed sequentially.
     Whereas work across multiple streams can be further controlled
-    using stream priorities and :obj:`Event` managements.
+    using stream priorities and :obj:`~_event.Event` managements.
 
     Advanced users can utilize default streams for enforce complex
     implicit synchronization behaviors.
 
-    Directly creating a :obj:`Stream` is not supported due to ambiguity.
-    New streams should instead be created through a :obj:`Device`
+    Directly creating a :obj:`~_stream.Stream` is not supported due to ambiguity.
+    New streams should instead be created through a :obj:`~_device.Device`
     object, or created directly through using an existing handle
     using Stream.from_handle().
 
@@ -173,14 +173,14 @@ def record(self, event: Event = None, options: EventOptions = None) -> Event:
 
         Parameters
         ----------
-        event : :obj:`Event`, optional
+        event : :obj:`~_event.Event`, optional
             Optional event object to be reused for recording.
         options : :obj:`EventOptions`, optional
             Customizable dataclass for event creation options.
 
         Returns
         -------
-        :obj:`Event`
+        :obj:`~_event.Event`
             Newly created event object.
 
         """
@@ -199,8 +199,8 @@ def wait(self, event_or_stream: Union[Event, Stream]):
 
         Waiting for an event or a stream establishes a stream order.
 
-        If a :obj:`Stream` is provided, then wait until the stream's
-        work is completed. This is done by recording a new :obj:`Event`
+        If a :obj:`~_stream.Stream` is provided, then wait until the stream's
+        work is completed. This is done by recording a new :obj:`~_event.Event`
         on the stream and then waiting on it.
 
         """
@@ -226,7 +226,7 @@ def wait(self, event_or_stream: Union[Event, Stream]):
 
     @property
     def device(self) -> Device:
-        """Return the :obj:`Device` singleton associated with this stream.
+        """Return the :obj:`~_device.Device` singleton associated with this stream.
 
         Note
         ----
@@ -246,7 +246,7 @@ def device(self) -> Device:
 
     @property
     def context(self) -> Context:
-        """Return the :obj:`Context` associated with this stream."""
+        """Return the :obj:`~_context.Context` associated with this stream."""
         if self._ctx_handle is None:
             self._ctx_handle = handle_return(cuda.cuStreamGetCtx(self._mnff.handle))
         if self._device_id is None:
@@ -255,10 +255,10 @@ def context(self) -> Context:
 
     @staticmethod
     def from_handle(handle: int) -> Stream:
-        """Create a new :obj:`Stream` object from a foreign stream handle.
+        """Create a new :obj:`~_stream.Stream` object from a foreign stream handle.
 
         Uses a cudaStream_t pointer address represented as a Python int
-        to create a new :obj:`Stream` object.
+        to create a new :obj:`~_stream.Stream` object.
 
         Note
         ----
@@ -273,7 +273,7 @@ def from_handle(handle: int) -> Stream:
 
         Returns
         -------
-        :obj:`Stream`
+        :obj:`~_stream.Stream`
             Newly created stream object.
 
         """
@@ -305,7 +305,7 @@ def __init__(self):
 
 
 def default_stream():
-    """Return the default CUDA :obj:`Stream`.
+    """Return the default CUDA :obj:`~_stream.Stream`.
 
     The type of default stream returned depends on if the environment
     variable CUDA_PYTHON_CUDA_PER_THREAD_DEFAULT_STREAM is set.