Doc improvements (#1978)

aamijar · web-flow · commit d6e6a5057612 · 2026-04-02T00:18:59.000Z
Introduces the following doc improvements: 1. Fix kmeans helpers not showing up correctly 2. Ensure pages are alphabetical under the different categories such as nearest-neighbors 3. Consistent subtitle naming from params to parameters 4. Fix python API multi gpu docs 5. New blogs and paper references 6. Fix missing struct members for preprocessing quantize 7. Fix typos and missing `#` from `include` Authors: - Anupam (https://github.com/aamijar) Approvers: - James Lamb (https://github.com/jameslamb) - Tamas Bela Feher (https://github.com/tfeher) URL: #1978
diff --git a/c/include/cuvs/neighbors/all_neighbors.h b/c/include/cuvs/neighbors/all_neighbors.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION.
+ * SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION.
  * SPDX-License-Identifier: Apache-2.0
  */
 
@@ -17,7 +17,7 @@ extern "C" {
 #endif
 
 /**
- * @defgroup all_neighbors_c_build All-neighbors C-API build
+ * @defgroup all_neighbors_c_params All-neighbors C-API build parameters
  * @{
  *
  * All-neighbors constructs an approximate k-NN graph for all vectors in a dataset.
@@ -78,6 +78,13 @@ cuvsError_t cuvsAllNeighborsIndexParamsCreate(cuvsAllNeighborsIndexParams_t* ind
  */
 cuvsError_t cuvsAllNeighborsIndexParamsDestroy(cuvsAllNeighborsIndexParams_t index_params);
 
+/** @} */
+
+/**
+ * @defgroup all_neighbors_c_build All-neighbors C-API build
+ * @{
+ */
+
 /**
  * @brief Build an all-neighbors k-NN graph automatically detecting host vs device dataset.
  *
diff --git a/cpp/include/cuvs/cluster/kmeans.hpp b/cpp/include/cuvs/cluster/kmeans.hpp
@@ -1573,15 +1573,14 @@ void cluster_cost(
  * @}
  */
 
+namespace helpers {
 /**
  * @defgroup kmeans_helpers k-means API helpers
  * @{
  */
 
-namespace helpers {
-
 /**
- * Automatically find the optimal value of k using a binary search.
+ * @brief Automatically find the optimal value of k using a binary search.
  * This method maximizes the Calinski-Harabasz Index while minimizing the per-cluster inertia.
  *
  *  @code{.cpp}
@@ -1626,10 +1625,9 @@ void find_k(raft::resources const& handle,
             int kmin    = 1,
             int maxiter = 100,
             float tol   = 1e-3);
-}  // namespace helpers
-
 /**
  * @}
  */
+}  // namespace helpers
 
 }  // namespace  cuvs::cluster::kmeans
diff --git a/cpp/include/cuvs/preprocessing/quantize/binary.hpp b/cpp/include/cuvs/preprocessing/quantize/binary.hpp
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: Copyright (c) 2024-2025, NVIDIA CORPORATION.
+ * SPDX-FileCopyrightText: Copyright (c) 2024-2026, NVIDIA CORPORATION.
  * SPDX-License-Identifier: Apache-2.0
  */
 
@@ -30,11 +30,10 @@ enum class bit_threshold { zero, mean, sampling_median };
  * @brief quantizer parameters.
  */
 struct params {
+  /** Threshold method for binarization. */
   bit_threshold threshold = bit_threshold::mean;
 
-  /*
-   * specifies the sampling ratio
-   */
+  /** Specifies the sampling ratio. */
   float sampling_ratio = 0.1;
 };
 
@@ -48,8 +47,10 @@ struct params {
  */
 template <typename T>
 struct quantizer {
+  /** Threshold vector used for binarization. */
   raft::device_vector<T, int64_t> threshold;
 
+  /** @brief Construct a quantizer with an empty threshold vector. */
   quantizer(raft::resources const& res) : threshold(raft::make_device_vector<T, int64_t>(res, 0)) {}
 };
 
diff --git a/cpp/include/cuvs/preprocessing/quantize/pq.hpp b/cpp/include/cuvs/preprocessing/quantize/pq.hpp
@@ -84,7 +84,9 @@ struct params {
  */
 template <typename T>
 struct quantizer {
+  /** Parameters used to build this quantizer. */
   params params_quantizer;
+  /** VPQ codebooks produced during training. */
   cuvs::neighbors::vpq_dataset<T, int64_t> vpq_codebooks;
 };
 
diff --git a/cpp/include/cuvs/preprocessing/quantize/scalar.hpp b/cpp/include/cuvs/preprocessing/quantize/scalar.hpp
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: Copyright (c) 2024-2025, NVIDIA CORPORATION.
+ * SPDX-FileCopyrightText: Copyright (c) 2024-2026, NVIDIA CORPORATION.
  * SPDX-License-Identifier: Apache-2.0
  */
 
@@ -24,9 +24,9 @@ namespace cuvs::preprocessing::quantize::scalar {
  * @brief quantizer parameters.
  */
 struct params {
-  /*
-   * specifies how many outliers at top & bottom will be ignored
-   * needs to be within range of (0, 1]
+  /**
+   * Specifies how many outliers at top & bottom will be ignored.
+   * Needs to be within range of (0, 1].
    */
   float quantile = 0.99;
 };
@@ -42,7 +42,9 @@ struct params {
  */
 template <typename T>
 struct quantizer {
+  /** Minimum value of the quantization range. */
   T min_;
+  /** Maximum value of the quantization range. */
   T max_;
 };
 
diff --git a/docs/source/c_api/neighbors.rst b/docs/source/c_api/neighbors.rst
@@ -9,11 +9,11 @@ Nearest Neighbors
    :maxdepth: 2
    :caption: Contents:
 
+   neighbors_all_neighbors_c.rst
    neighbors_bruteforce_c.rst
-   neighbors_ivf_flat_c.rst
-   neighbors_ivf_pq_c.rst
    neighbors_cagra_c.rst
    neighbors_hnsw_c.rst
+   neighbors_ivf_flat_c.rst
+   neighbors_ivf_pq_c.rst
    neighbors_mg.rst
-   neighbors_all_neighbors_c.rst
    neighbors_vamana_c.rst
diff --git a/docs/source/c_api/neighbors_all_neighbors_c.rst b/docs/source/c_api/neighbors_all_neighbors_c.rst
@@ -9,6 +9,14 @@ The all-neighbors method constructs a k-NN graph for all vectors in a dataset. I
 
 ``#include <cuvs/neighbors/all_neighbors.h>``
 
+Build parameters
+----------------
+
+.. doxygengroup:: all_neighbors_c_params
+    :project: cuvs
+    :members:
+    :content-only:
+
 Build
 -----
 
diff --git a/docs/source/cpp_api/cluster.rst b/docs/source/cpp_api/cluster.rst
@@ -9,6 +9,6 @@ Cluster
    :maxdepth: 2
    :caption: Contents:
 
-   cluster_kmeans.rst
    cluster_agglomerative.rst
+   cluster_kmeans.rst
    cluster_spectral.rst
diff --git a/docs/source/cpp_api/cluster_agglomerative.rst b/docs/source/cpp_api/cluster_agglomerative.rst
@@ -5,8 +5,8 @@ Agglomerative
    :language: c++
    :class: highlight
 
-Params
-------
+Parameters
+----------
 
 ``#include <cuvs/cluster/agglomerative.hpp>``
 
@@ -18,10 +18,10 @@ namespace *cuvs::cluster::agglomerative*
    :content-only:
 
 
-Single-linkage
---------------
+Agglomerative
+-------------
 
-``include <cuvs/cluster/agglomerative.hpp>``
+``#include <cuvs/cluster/agglomerative.hpp>``
 
 namespace *cuvs::cluster::agglomerative*
 
diff --git a/docs/source/cpp_api/cluster_kmeans.rst b/docs/source/cpp_api/cluster_kmeans.rst
@@ -5,8 +5,8 @@ K-Means
    :language: c++
    :class: highlight
 
-Params
-------
+Parameters
+----------
 
 ``#include <cuvs/cluster/kmeans.hpp>``
 
@@ -21,7 +21,7 @@ namespace *cuvs::cluster::kmeans*
 K-means
 -------
 
-``include <cuvs/cluster/kmeans.hpp>``
+``#include <cuvs/cluster/kmeans.hpp>``
 
 namespace *cuvs::cluster::kmeans*
 
@@ -34,7 +34,7 @@ namespace *cuvs::cluster::kmeans*
 K-means Helpers
 ---------------
 
-``include <cuvs/cluster/kmeans.hpp>``
+``#include <cuvs/cluster/kmeans.hpp>``
 
 namespace *cuvs::cluster::kmeans::helpers*
 
diff --git a/docs/source/cpp_api/distance.rst b/docs/source/cpp_api/distance.rst
@@ -22,7 +22,7 @@ namespace *cuvs::distance*
 Pairwise Distances
 ------------------
 
-``include <cuvs/distance/distance.hpp>``
+``#include <cuvs/distance/distance.hpp>``
 
 namespace *cuvs::distance*
 
diff --git a/docs/source/cpp_api/neighbors.rst b/docs/source/cpp_api/neighbors.rst
@@ -18,7 +18,7 @@ Nearest Neighbors
    neighbors_hnsw.rst
    neighbors_ivf_flat.rst
    neighbors_ivf_pq.rst
+   neighbors_mg.rst
    neighbors_nn_descent.rst
    neighbors_refine.rst
-   neighbors_mg.rst
    neighbors_vamana.rst
diff --git a/docs/source/cpp_api/neighbors_all_neighbors.rst b/docs/source/cpp_api/neighbors_all_neighbors.rst
@@ -1,7 +1,7 @@
-All-neighbors
+All-Neighbors
 =============
 
-All-neighbors allows building an approximate all-neighbors knn graph. Given a full dataset, it finds nearest neighbors for all the training vectors in the dataset.
+All-Neighbors allows building an approximate all-neighbors knn graph. Given a full dataset, it finds nearest neighbors for all the training vectors in the dataset.
 
 .. role:: py(code)
    :language: c++
@@ -11,8 +11,8 @@ All-neighbors allows building an approximate all-neighbors knn graph. Given a fu
 
 namespace *cuvs::neighbors::all_neighbors*
 
-All neighbors knn graph build parameters
-----------------------------------------
+Build Parameters
+----------------
 
 .. doxygengroup:: all_neighbors_cpp_params
     :project: cuvs
diff --git a/docs/source/cpp_api/neighbors_mg.rst b/docs/source/cpp_api/neighbors_mg.rst
@@ -1,7 +1,7 @@
-Distributed ANN
-===============
+Multi-GPU Nearest Neighbors
+===========================
 
-The SNMG (single-node multi-GPUs) ANN API provides a set of functions to deploy ANN indexes on multiple GPUs.
+The Multi-GPU (SNMG - single-node multi-GPUs) nearest neighbors API provides a set of functions to deploy ANN indexes across multiple GPUs for improved performance and scalability.
 
 .. role:: py(code)
    :language: c++
diff --git a/docs/source/cpp_api/preprocessing_pca.rst b/docs/source/cpp_api/preprocessing_pca.rst
@@ -11,7 +11,7 @@ Principal Component Analysis (PCA) is a linear dimensionality reduction techniqu
 
 namespace *cuvs::preprocessing::pca*
 
-Params
+Parameters
 ----------
 
 .. doxygenstruct:: cuvs::preprocessing::pca::params
diff --git a/docs/source/cpp_api/preprocessing_quantize.rst b/docs/source/cpp_api/preprocessing_quantize.rst
@@ -8,25 +8,17 @@ This page provides C++ class references for the publicly-exposed elements of the
    :language: c++
    :class: highlight
 
-Scalar
-------
-
-``#include <cuvs/preprocessing/quantize/scalar.hpp>``
-
-namespace *cuvs::preprocessing::quantize::scalar*
-
-.. doxygengroup:: scalar
-   :project: cuvs
-
-Binary
-------
+Binary Quantizer
+----------------
 
 ``#include <cuvs/preprocessing/quantize/binary.hpp>``
 
 namespace *cuvs::preprocessing::quantize::binary*
 
 .. doxygengroup:: binary
    :project: cuvs
+   :members:
+   :content-only:
 
 Product Quantizer
 -----------------
@@ -37,3 +29,17 @@ namespace *cuvs::preprocessing::quantize::pq*
 
 .. doxygengroup:: pq
    :project: cuvs
+   :members:
+   :content-only:
+
+Scalar Quantizer
+----------------
+
+``#include <cuvs/preprocessing/quantize/scalar.hpp>``
+
+namespace *cuvs::preprocessing::quantize::scalar*
+
+.. doxygengroup:: scalar
+   :project: cuvs
+   :members:
+   :content-only:
diff --git a/docs/source/cpp_api/preprocessing_spectral_embedding.rst b/docs/source/cpp_api/preprocessing_spectral_embedding.rst
@@ -31,8 +31,8 @@ namespace *cuvs::preprocessing::spectral_embedding*
    :project: cuvs
    :members:
 
-Functions
----------
+Spectral Embedding
+------------------
 
 ``#include <cuvs/preprocessing/spectral_embedding.hpp>``
 
diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst
@@ -86,8 +86,9 @@ Blogs
 
 We frequently publish blogs on GPU-enabled vector search, which can provide great deep dives into various important topics and breakthroughs:
 
+#. `See all cuVS blogs <https://developer.nvidia.com/blog/recent-posts/?products=cuVS>`_
 #. `Accelerated Vector Search: Approximating with cuVS IVF-Flat <https://developer.nvidia.com/blog/accelerated-vector-search-approximating-with-rapids-raft-ivf-flat/>`_
-#. `Accelerating Vector Search with cuVS IVF-PQ <https://developer.nvidia.com/blog/accelerating-vector-search-rapids-cuvs-ivf-pq-deep-dive-part-1/>`_
+#. Accelerating Vector Search with cuVS IVF-PQ (`Part 1 <https://developer.nvidia.com/blog/accelerating-vector-search-rapids-cuvs-ivf-pq-deep-dive-part-1/>`_, `Part 2 <https://developer.nvidia.com/blog/accelerating-vector-search-nvidia-cuvs-ivf-pq-performance-tuning-part-2/>`_)
 
 Research
 --------
@@ -99,6 +100,7 @@ For the interested reader, many of the accelerated implementations in cuVS are a
 #. `Fast K-NN Graph Construction by GPU Based NN-Descent <https://dl.acm.org/doi/abs/10.1145/3459637.3482344?casa_token=O_nan1B1F5cAAAAA:QHWDEhh0wmd6UUTLY9_Gv6c3XI-5DXM9mXVaUXOYeStlpxTPmV3nKvABRfoivZAaQ3n8FWyrkWw>`_
 #. `cuSLINK: Single-linkage Agglomerative Clustering on the GPU <https://arxiv.org/abs/2306.16354>`_
 #. `GPU Semiring Primitives for Sparse Neighborhood Methods <https://arxiv.org/abs/2104.06357>`_
+#. `VecFlow: A High-Performance Vector Data Management System for Filtered-Search on GPUs <https://arxiv.org/abs/2506.00812>`_
 
 
 Get involved
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -63,7 +63,7 @@ There are several benefits to using cuVS and GPUs for vector search, including
 6. Multiple language support
 7. Building blocks for composing new or accelerating existing algorithms
 
-In addition to the items above, cuVS shoulders the responsibility of keeping non-trivial accelerated code up to date as new NVIDIA architectures and CUDA versions are released. This provides a deslightful development experimence, guaranteeing that any libraries, databases, or applications built on top of it will always be receiving the best performance and scale.
+In addition to the items above, cuVS shoulders the responsibility of keeping non-trivial accelerated code up to date as new NVIDIA architectures and CUDA versions are released. This provides a delightful development experience, guaranteeing that any libraries, databases, or applications built on top of it will always be receiving the best performance and scale.
 
 cuVS Technology Stack
 #####################
diff --git a/docs/source/python_api/neighbors.rst b/docs/source/python_api/neighbors.rst
@@ -5,26 +5,15 @@ Nearest Neighbors
    :language: python
    :class: highlight
 
-Single-GPU Algorithms
-#####################
-
 .. toctree::
    :maxdepth: 2
-   :caption: Single-GPU ANN Algorithms:
+   :caption: Contents:
 
+   neighbors_all_neighbors.rst
    neighbors_brute_force.rst
    neighbors_cagra.rst
    neighbors_hnsw.rst
    neighbors_ivf_flat.rst
    neighbors_ivf_pq.rst
-   neighbors_nn_decent.rst
-
-Multi-GPU Algorithms
-####################
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Multi-GPU Distributed ANN:
-
    neighbors_multi_gpu.rst
-   neighbors_all_neighbors.rst
+   neighbors_nn_decent.rst
diff --git a/docs/source/python_api/neighbors_all_neighbors.rst b/docs/source/python_api/neighbors_all_neighbors.rst
diff --git a/docs/source/python_api/neighbors_multi_gpu.rst b/docs/source/python_api/neighbors_multi_gpu.rst
