Documentation Fixes (#1301)

This fixes all the warnings in the docs build, and enables warnings as errors to prevent future regressions

Authors:
  - Ben Frederickson (https://github.com/benfred)
  - Corey J. Nolet (https://github.com/cjnolet)

Approvers:
  - Corey J. Nolet (https://github.com/cjnolet)
  - Kyle Edwards (https://github.com/KyleFromNVIDIA)

URL: #1301

Author: benfred

build.sh

@@ -517,7 +517,7 @@ if hasArg docs; then
     cd "${DOXYGEN_BUILD_DIR}"
     doxygen Doxyfile
     cd "${SPHINX_BUILD_DIR}"
-    sphinx-build -b html source _html
+    sphinx-build -W -b html source _html
     cd "${REPODIR}"/rust
     cargo doc -p cuvs --no-deps
     rsync -av "${RUST_BUILD_DIR}"/doc/ "${SPHINX_BUILD_DIR}"/_html/_static/rust

cpp/doxygen/Doxyfile

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2024, NVIDIA CORPORATION.
+ * Copyright (c) 2024-2025, NVIDIA CORPORATION.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -167,7 +167,7 @@ cuvsError_t cuvsBruteForceSearch(cuvsResources_t res,
  */
 
 /**
- * @defgroup bruteforce_c_serialize BRUTEFORCE C-API serialize functions
+ * @defgroup bruteforce_c_index_serialize BRUTEFORCE C-API serialize functions
  * @{
  */
 /**

cpp/include/cuvs/neighbors/brute_force.h

@@ -605,7 +605,7 @@ cuvsError_t cuvsCagraSearch(cuvsResources_t res,
  */
 
 /**
- * @defgroup cagra_c_serialize CAGRA C-API serialize functions
+ * @defgroup cagra_c_index_serialize CAGRA C-API serialize functions
  * @{
  */
 /**

cpp/include/cuvs/neighbors/cagra.h

@@ -340,11 +340,13 @@ struct index : cuvs::neighbors::index {
   }
 
   // Don't allow copying the index for performance reasons (try avoiding copying data)
+  /** \cond */
   index(const index&)                    = delete;
   index(index&&)                         = default;
   auto operator=(const index&) -> index& = delete;
   auto operator=(index&&) -> index&      = default;
   ~index()                               = default;
+  /** \endcond */
 
   /** Construct an empty index. */
   index(raft::resources const& res,

cpp/include/cuvs/neighbors/cagra.hpp

@@ -491,6 +491,7 @@ struct base_filter {
 
 /* A filter that filters nothing. This is the default behavior. */
 struct none_sample_filter : public base_filter {
+  /** \cond */
   constexpr __forceinline__ _RAFT_HOST_DEVICE bool operator()(
     // query index
     const uint32_t query_ix,
@@ -504,7 +505,7 @@ struct none_sample_filter : public base_filter {
     const uint32_t query_ix,
     // the index of the current sample
     const uint32_t sample_ix) const;
-
+  /** \endcond */
   FilterType get_filter_type() const override { return FilterType::None; }
 };
 
@@ -523,6 +524,7 @@ struct ivf_to_sample_filter : public base_filter {
 
   ivf_to_sample_filter(const index_t* const* inds_ptrs, const filter_t next_filter);
 
+  /** \cond */
   /** If the original filter takes three arguments, then don't modify the arguments.
    * If the original filter takes two arguments, then we are using `inds_ptr_` to obtain the sample
    * index.
@@ -536,6 +538,7 @@ struct ivf_to_sample_filter : public base_filter {
     const uint32_t sample_ix) const;
 
   FilterType get_filter_type() const override { return next_filter_.get_filter_type(); }
+  /** \endcond */
 };
 
 /**
@@ -552,11 +555,13 @@ struct bitmap_filter : public base_filter {
   const view_t bitmap_view_;
 
   bitmap_filter(const view_t bitmap_for_filtering);
+  /** \cond */
   inline _RAFT_HOST_DEVICE bool operator()(
     // query index
     const uint32_t query_ix,
     // the index of the current sample
     const uint32_t sample_ix) const;
+  /** \endcond */
 
   FilterType get_filter_type() const override { return FilterType::Bitmap; }
 
@@ -579,12 +584,14 @@ struct bitset_filter : public base_filter {
   // View of the bitset to use as a filter
   const view_t bitset_view_;
 
+  /** \cond */
   _RAFT_HOST_DEVICE bitset_filter(const view_t bitset_for_filtering);
   constexpr __forceinline__ _RAFT_HOST_DEVICE bool operator()(
     // query index
     const uint32_t query_ix,
     // the index of the current sample
     const uint32_t sample_ix) const;
+  /** \endcond */
 
   FilterType get_filter_type() const override { return FilterType::Bitset; }
 

cpp/include/cuvs/neighbors/common.hpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2024, NVIDIA CORPORATION.
+ * Copyright (c) 2024-2025, NVIDIA CORPORATION.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -369,7 +369,7 @@ cuvsError_t cuvsHnswSearch(cuvsResources_t res,
  */
 
 /**
- * @defgroup hnsw_c_serialize HNSW C-API serialize functions
+ * @defgroup hnsw_c_index_serialize HNSW C-API serialize functions
  * @{
  */
 

cpp/include/cuvs/neighbors/hnsw.h

@@ -97,7 +97,9 @@ cuvs::neighbors::cagra::index_params to_cagra_params(
   int ef_construction,
   cuvs::distance::DistanceType metric = cuvs::distance::DistanceType::L2Expanded);
 
-/**@}*/
+/**
+ * @}
+ */
 
 /**
  * @defgroup hnsw_cpp_index hnswlib index wrapper
@@ -127,7 +129,7 @@ struct index : cuvs::neighbors::index {
   /**
   @brief Get underlying index
   */
-  virtual auto get_index() const -> void const* = 0;
+  virtual void const* get_index() const = 0;
 
   auto dim() const -> int const { return dim_; }
 
@@ -146,7 +148,9 @@ struct index : cuvs::neighbors::index {
   HnswHierarchy hierarchy_;
 };
 
-/**@}*/
+/**
+ * @}
+ */
 
 /**
  * @defgroup hnsw_cpp_extend_params HNSW index extend parameters
@@ -308,7 +312,9 @@ std::unique_ptr<index<int8_t>> from_cagra(
   std::optional<raft::host_matrix_view<const int8_t, int64_t, raft::row_major>> dataset =
     std::nullopt);
 
-/**@}*/
+/**
+ * @}
+ */
 
 /**
  * @defgroup hnsw_cpp_index_extend Extend HNSW index with additional vectors
@@ -342,6 +348,7 @@ std::unique_ptr<index<int8_t>> from_cagra(
  *   auto additional_dataset = raft::make_host_matrix<float>(res, add_size, index->dim());
  *   hnsw::extend_params extend_params;
  *   hnsw::extend(res, extend_params, additional_dataset, *hnsw_index.get());
+ * @endcode
  */
 void extend(raft::resources const& res,
             const extend_params& params,
@@ -375,6 +382,7 @@ void extend(raft::resources const& res,
  *   auto additional_dataset = raft::make_host_matrix<half>(res, add_size, index->dim());
  *   hnsw::extend_params extend_params;
  *   hnsw::extend(res, extend_params, additional_dataset, *hnsw_index.get());
+ * @endcode
  */
 void extend(raft::resources const& res,
             const extend_params& params,
@@ -408,6 +416,7 @@ void extend(raft::resources const& res,
  *   auto additional_dataset = raft::make_host_matrix<uint8_t>(res, add_size, index->dim());
  *   hnsw::extend_params extend_params;
  *   hnsw::extend(res, extend_params, additional_dataset, *hnsw_index.get());
+ * @endcode
  */
 void extend(raft::resources const& res,
             const extend_params& params,
@@ -441,13 +450,16 @@ void extend(raft::resources const& res,
  *   auto additional_dataset = raft::make_host_matrix<int8_t>(res, add_size, index->dim());
  *   hnsw::extend_params extend_params;
  *   hnsw::extend(res, extend_params, additional_dataset, *hnsw_index.get());
+ * @endcode
  */
 void extend(raft::resources const& res,
             const extend_params& params,
             raft::host_matrix_view<const int8_t, int64_t, raft::row_major> additional_dataset,
             index<int8_t>& idx);
 
-/**@} */
+/**
+ * @}
+ */
 
 /**
  * @defgroup hnsw_cpp_search_params Build CAGRA index and search with hnswlib
@@ -460,7 +472,9 @@ struct search_params : cuvs::neighbors::search_params {
                         // automatically maximizes parallelism
 };
 
-/**@}*/
+/**
+ * @}
+ */
 
 // TODO: Filtered Search APIs: https://github.com/rapidsai/cuvs/issues/363
 
@@ -645,7 +659,9 @@ void search(raft::resources const& res,
             raft::host_matrix_view<uint64_t, int64_t, raft::row_major> neighbors,
             raft::host_matrix_view<float, int64_t, raft::row_major> distances);
 
-/**@}*/
+/**
+ * @}
+ */
 
 /**
  * @defgroup hnsw_cpp_index_serialize Deserialize CAGRA index as hnswlib index
@@ -940,7 +956,9 @@ void deserialize(raft::resources const& res,
                  cuvs::distance::DistanceType metric,
                  index<int8_t>** index);
 
-/**@}*/
+/**
+ * @}
+ */
 
 }  // namespace cuvs::neighbors::hnsw
 

cpp/include/cuvs/neighbors/hnsw.hpp

@@ -300,7 +300,7 @@ cuvsError_t cuvsIvfFlatSearch(cuvsResources_t res,
  */
 
 /**
- * @defgroup ivf_flat_c_serialize IVF-Flat C-API serialize functions
+ * @defgroup ivf_flat_c_index_serialize IVF-Flat C-API serialize functions
  * @{
  */
 /**

cpp/include/cuvs/neighbors/ivf_flat.h

@@ -405,7 +405,7 @@ cuvsError_t cuvsIvfPqSearch(cuvsResources_t res,
  */
 
 /**
- * @defgroup ivf_pq_c_serialize IVF-PQ C-API serialize functions
+ * @defgroup ivf_pq_c_index_serialize IVF-PQ C-API serialize functions
  * @{
  */
 /**