Add more pylibcudf source annotations

docs/cudf/source/conf.py

@@ -39,6 +39,7 @@
 from sphinx.ext import intersphinx
 from sphinx.ext.autodoc import ClassDocumenter
 from sphinx.highlighting import lexers
+from sphinx.util.nodes import make_refnode
 
 
 class PseudoLexer(RegexLexer):
@@ -497,6 +498,26 @@ def _cached_intersphinx_lookup(env, node, contnode):
     return ref
 
 
+def _resolve_cpp_xref(app, env, node, contnode, name):
+    docname, objtype, anchor = _domain_objects[name]
+    for reftype in (node["reftype"], objtype):
+        if (
+            ref := env.domains["cpp"].resolve_xref(
+                env,
+                docname,
+                app.builder,
+                reftype,
+                name,
+                node,
+                contnode,
+            )
+        ) is not None:
+            return ref
+    return make_refnode(
+        app.builder, env.docname, docname, anchor, contnode, name
+    )
+
+
 def on_missing_reference(app, env, node, contnode):
     # These variables are defined outside the function to speed up the build.
     global \
@@ -512,8 +533,10 @@ def on_missing_reference(app, env, node, contnode):
     if _domain_objects is None:
         _domain_objects = {}
         _prefixed_domain_objects = {}
-        for name, _, _, docname, _, _ in env.domains["cpp"].get_objects():
-            _domain_objects[name] = docname
+        for name, _, objtype, docname, anchor, _ in env.domains[
+            "cpp"
+        ].get_objects():
+            _domain_objects[name] = (docname, objtype, anchor)
             for prefix in _all_namespaces:
                 _prefixed_domain_objects[f"{prefix}{name}"] = name
 
@@ -562,6 +585,15 @@ def on_missing_reference(app, env, node, contnode):
         if match := re.search("(.*)<.*>", reftarget):
             reftarget = match.group(1)
 
+        # Breathe sometimes emits bare C++ targets that are already registered
+        # in the C++ domain, for example enum types in parameter lists.
+        if (
+            reftarget in _domain_objects
+            and (ref := _resolve_cpp_xref(app, env, node, contnode, reftarget))
+            is not None
+        ):
+            return ref
+
         # Try to find the target prefixed with e.g. namespaces in case that's
         # all that's missing.
         # We need to do this search because the call sites may not have used
@@ -576,15 +608,7 @@ def on_missing_reference(app, env, node, contnode):
                     name = f"{prefix}{reftarget}"
                     break
         if name is not None:
-            return env.domains["cpp"].resolve_xref(
-                env,
-                _domain_objects[name],
-                app.builder,
-                node["reftype"],
-                name,
-                node,
-                contnode,
-            )
+            return _resolve_cpp_xref(app, env, node, contnode, name)
 
         # Final possibility is an intersphinx lookup to see if the symbol
         # exists in one of the other inventories. First we check the symbol

python/pylibcudf/pylibcudf/column.pyx

@@ -615,7 +615,7 @@ cdef class Column:
         DataType dtype,
         size_type size,
         children: Iterable[Column],
-    ):
+    ) -> Column:
         """
         Create a Column from an RMM DeviceBuffer.
 
@@ -825,7 +825,7 @@ cdef class Column:
         size_type size,
         object stream: CudaStreamLike | None = None,
         DeviceMemoryResource mr=None,
-    ):
+    ) -> Column:
         """Create a Column from a Scalar.
 
         Parameters
@@ -894,7 +894,7 @@ cdef class Column:
         size_type size,
         object stream: CudaStreamLike | None = None,
         DeviceMemoryResource mr=None,
-    ):
+    ) -> Column:
         """Create an all null column from a template.
 
         Parameters
@@ -988,7 +988,7 @@ cdef class Column:
         cls,
         obj: SupportsArrayInterface,
         object stream: CudaStreamLike | None = None,
-    ):
+    ) -> Column:
         """
         Create a Column from an object implementing the NumPy Array Interface.
 
@@ -1046,7 +1046,7 @@ cdef class Column:
         cls,
         obj: SupportsCudaArrayInterface,
         object stream: CudaStreamLike | None = None,
-    ):
+    ) -> Column:
         """
         Create a Column from an object implementing the CUDA Array Interface.
 
@@ -1089,7 +1089,7 @@ cdef class Column:
         cls,
         obj: SupportsCudaArrayInterface | SupportsArrayInterface,
         object stream: CudaStreamLike | None = None,
-    ):
+    ) -> Column:
         """
         Create a Column from any object which supports the NumPy
         or CUDA array interface.
@@ -1308,7 +1308,7 @@ cdef class Column:
                     release_arrow_array_raw(raw_host_array_ptr)
 
     @classmethod
-    def struct_from_children(cls, children: Iterable[Column]):
+    def struct_from_children(cls, children: Iterable[Column]) -> Column:
         """
         Create a struct Column from a list of child columns.
 

python/pylibcudf/pylibcudf/io/avro.pyx

@@ -34,7 +34,7 @@ cdef class AvroReaderOptions:
     For details, see :cpp:class:`cudf::io::avro_reader_options`
     """
     @staticmethod
-    def builder(SourceInfo source):
+    def builder(SourceInfo source) -> AvroReaderOptionsBuilder:
         """
         Create a AvroWriterOptionsBuilder object
 
@@ -93,6 +93,8 @@ cdef class AvroReaderOptions:
 
 
 cdef class AvroReaderOptionsBuilder:
+    """Builder to build options for ``read_avro``."""
+
     cpdef AvroReaderOptionsBuilder columns(self, list col_names: list[str]):
         """
         Set names of the column to be read.

python/pylibcudf/pylibcudf/io/csv.pyx

@@ -53,7 +53,7 @@ cdef class CsvReaderOptions:
     For details, see :cpp:class:`cudf::io::csv_reader_options`
     """
     @staticmethod
-    def builder(SourceInfo source):
+    def builder(SourceInfo source) -> CsvReaderOptionsBuilder:
         """
         Create a CsvWriterOptionsBuilder object
 
@@ -715,7 +715,7 @@ cdef class CsvWriterOptions:
     For details, see :cpp:class:`cudf::io::csv_writer_options`
     """
     @staticmethod
-    def builder(SinkInfo sink, Table table):
+    def builder(SinkInfo sink, Table table) -> CsvWriterOptionsBuilder:
         """Create a CsvWriterOptionsBuilder object
 
         For details, see :cpp:func:`cudf::io::csv_writer_options::builder`

python/pylibcudf/pylibcudf/io/json.pxd

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: Copyright (c) 2024-2026, NVIDIA CORPORATION.
+# SPDX-FileCopyrightText: Copyright (c) 2024-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 from libcpp cimport bool
 from libcpp.map cimport map
@@ -79,7 +79,7 @@ cdef class JsonReaderOptionsBuilder:
     )
     cpdef JsonReaderOptionsBuilder strict_validation(self, bool val)
     cpdef JsonReaderOptionsBuilder unquoted_control_chars(self, bool val)
-    cpdef build(self)
+    cpdef JsonReaderOptions build(self)
 
 cpdef TableWithMetadata read_json(
     JsonReaderOptions options, object stream = *, DeviceMemoryResource mr = *

python/pylibcudf/pylibcudf/io/json.pyx

@@ -162,7 +162,7 @@ cdef class JsonReaderOptions:
     For details, see `:cpp:class:`cudf::io::json_reader_options`
     """
     @staticmethod
-    def builder(SourceInfo source):
+    def builder(SourceInfo source) -> JsonReaderOptionsBuilder:
         """
         Create a JsonReaderOptionsBuilder object
 
@@ -362,6 +362,8 @@ cdef class JsonReaderOptions:
 
 
 cdef class JsonReaderOptionsBuilder:
+    """Builder to build options for ``read_json``."""
+
     cpdef JsonReaderOptionsBuilder byte_range_offset(self, size_t byte_range_offset):
         """
         Set number of bytes to skip from source start.
@@ -701,7 +703,7 @@ cdef class JsonReaderOptionsBuilder:
         self.c_obj.unquoted_control_chars(val)
         return self
 
-    cpdef build(self):
+    cpdef JsonReaderOptions build(self):
         """Create a JsonReaderOptions object"""
         cdef JsonReaderOptions json_options = JsonReaderOptions.__new__(
             JsonReaderOptions
@@ -911,7 +913,7 @@ cdef class JsonWriterOptions:
     For details, see :cpp:class:`cudf::io::json_writer_options`
     """
     @staticmethod
-    def builder(SinkInfo sink, Table table):
+    def builder(SinkInfo sink, Table table) -> JsonWriterOptionsBuilder:
         """
         Create a JsonWriterOptionsBuilder object
 
@@ -996,6 +998,8 @@ cdef class JsonWriterOptions:
         self.c_obj.set_compression(comptype)
 
 cdef class JsonWriterOptionsBuilder:
+    """Builder to build options for ``write_json``."""
+
     cpdef JsonWriterOptionsBuilder metadata(self, TableWithMetadata tbl_w_meta):
         """
         Sets optional metadata (with column names).

python/pylibcudf/pylibcudf/io/orc.pyx

@@ -275,7 +275,7 @@ cdef class OrcReaderOptions:
     For details, see :cpp:class:`cudf::io::orc_reader_options`
     """
     @staticmethod
-    def builder(SourceInfo source):
+    def builder(SourceInfo source) -> OrcReaderOptionsBuilder:
         """
         Create a OrcReaderOptionsBuilder object
 
@@ -423,6 +423,8 @@ cdef class OrcReaderOptions:
         self.c_obj.set_source(src.c_obj)
 
 cdef class OrcReaderOptionsBuilder:
+    """Builder to build options for ``read_orc``."""
+
     cpdef OrcReaderOptionsBuilder use_index(self, bool use):
         """
         Enable/Disable use of row index to speed-up reading.
@@ -507,6 +509,8 @@ cpdef ParsedOrcStatistics read_parsed_orc_statistics(
 
 
 cdef class OrcWriterOptions:
+    """The settings to use for ``write_orc``."""
+
     cpdef void set_stripe_size_bytes(self, size_t size_bytes):
         """
         Sets the maximum stripe size, in bytes.
@@ -564,7 +568,7 @@ cdef class OrcWriterOptions:
         self.c_obj.set_row_index_stride(stride)
 
     @staticmethod
-    def builder(SinkInfo sink, Table table):
+    def builder(SinkInfo sink, Table table) -> OrcWriterOptionsBuilder:
         """
         Create builder to create OrcWriterOptions.
 
@@ -591,6 +595,8 @@ cdef class OrcWriterOptions:
 
 
 cdef class OrcWriterOptionsBuilder:
+    """Builder to build options for ``write_orc``."""
+
     cpdef OrcWriterOptionsBuilder compression(self, compression_type comp):
         """
         Sets compression type.
@@ -613,7 +619,7 @@ cdef class OrcWriterOptionsBuilder:
         """
         Choose granularity of column statistics to be written.
 
-        For details, see :cpp:func:`enable_statistics`
+        For details, see :cpp:func:`cudf::io::orc_writer_options_builder::enable_statistics`
 
         Parameters
         ----------
@@ -758,6 +764,8 @@ cdef class OrcChunkedWriter:
 
 
 cdef class ChunkedOrcWriterOptions:
+    """The settings to use for chunked ORC writing."""
+
     cpdef void set_stripe_size_bytes(self, size_t size_bytes):
         """
         Sets the maximum stripe size, in bytes.
@@ -809,7 +817,7 @@ cdef class ChunkedOrcWriterOptions:
         self.c_obj.set_row_index_stride(stride)
 
     @staticmethod
-    def builder(SinkInfo sink):
+    def builder(SinkInfo sink) -> ChunkedOrcWriterOptionsBuilder:
         """
         Create builder to create ChunkedOrcWriterOptions.
 
@@ -834,6 +842,8 @@ cdef class ChunkedOrcWriterOptions:
 
 
 cdef class ChunkedOrcWriterOptionsBuilder:
+    """Builder to build options for chunked ORC writing."""
+
     cpdef ChunkedOrcWriterOptionsBuilder compression(self, compression_type comp):
         """
         Sets compression type.

python/pylibcudf/pylibcudf/io/parquet.pxd

@@ -73,7 +73,7 @@ cdef class ParquetReaderOptionsBuilder:
     cpdef ParquetReaderOptionsBuilder use_jit_filter(self, bool use_jit_filter)
     cpdef ParquetReaderOptionsBuilder case_sensitive_names(self, bool val)
     cpdef ParquetReaderOptionsBuilder decimal_width(self, type_id width)
-    cpdef build(self)
+    cpdef ParquetReaderOptions build(self)
 
 
 cdef class ChunkedParquetReader:

python/pylibcudf/pylibcudf/io/parquet.pyx

@@ -119,7 +119,7 @@ cdef class ParquetReaderOptions:
     For details, see :cpp:class:`cudf::io::parquet_reader_options`
     """
     @staticmethod
-    def builder(SourceInfo source):
+    def builder(SourceInfo source) -> ParquetReaderOptionsBuilder:
         """
         Create a ParquetReaderOptionsBuilder object
 
@@ -344,6 +344,8 @@ cdef class ParquetReaderOptions:
         return self.c_obj.is_enabled_case_sensitive_names()
 
 cdef class ParquetReaderOptionsBuilder:
+    """Builder to build options for ``read_parquet``."""
+
     cpdef ParquetReaderOptionsBuilder convert_strings_to_categories(self, bool val):
         """
         Sets enable/disable conversion of strings to categories.
@@ -567,7 +569,7 @@ cdef class ParquetReaderOptionsBuilder:
         self.c_obj.decimal_width(width)
         return self
 
-    cpdef build(self):
+    cpdef ParquetReaderOptions build(self):
         """Create a ParquetReaderOptions object"""
         cdef ParquetReaderOptions parquet_options = ParquetReaderOptions.__new__(
             ParquetReaderOptions
@@ -834,8 +836,10 @@ cdef class ChunkedParquetWriter:
 
 
 cdef class ChunkedParquetWriterOptions:
+    """The settings to use for chunked Parquet writing."""
+
     @staticmethod
-    def builder(SinkInfo sink):
+    def builder(SinkInfo sink) -> ChunkedParquetWriterOptionsBuilder:
         """
         Create builder to create ChunkedParquetWriterOptions.
 
@@ -874,6 +878,8 @@ cdef class ChunkedParquetWriterOptions:
 
 
 cdef class ChunkedParquetWriterOptionsBuilder:
+    """Builder to build options for chunked Parquet writing."""
+
     cpdef ChunkedParquetWriterOptionsBuilder metadata(
         self,
         TableInputMetadata metadata
@@ -1046,9 +1052,10 @@ cdef class ChunkedParquetWriterOptionsBuilder:
 
 
 cdef class ParquetWriterOptions:
+    """The settings to use for ``write_parquet``."""
 
     @staticmethod
-    def builder(SinkInfo sink, Table table):
+    def builder(SinkInfo sink, Table table) -> ParquetWriterOptionsBuilder:
         """
         Create builder to create ParquetWriterOptionsBuilder.
 
@@ -1186,6 +1193,7 @@ cdef class ParquetWriterOptions:
 
 
 cdef class ParquetWriterOptionsBuilder:
+    """Builder to build options for ``write_parquet``."""
 
     cpdef ParquetWriterOptionsBuilder metadata(self, TableInputMetadata metadata):
         """