Various updates to the docs for 23.06 release (#1538)

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

Approvers:
  - Divye Gala (https://github.com/divyegala)

URL: #1538

cpp/include/raft/core/device_span.hpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, NVIDIA CORPORATION.
+ * Copyright (c) 2022-2023, NVIDIA CORPORATION.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -20,10 +20,18 @@
 
 namespace raft {
 
+/**
+ * @defgroup device_span one-dimensional device span type
+ * @{
+ */
+
 /**
  * @brief A span class for device pointer.
  */
 template <typename T, size_t extent = std::experimental::dynamic_extent>
 using device_span = span<T, true, extent>;
 
+/**
+ * @}
+ */
 }  // end namespace raft

cpp/include/raft/core/host_mdarray.hpp

@@ -67,6 +67,11 @@ template <typename ElementType,
           typename LayoutPolicy = layout_c_contiguous>
 using host_matrix = host_mdarray<ElementType, matrix_extent<IndexType>, LayoutPolicy>;
 
+/**
+ * @defgroup host_mdarray_factories factories to create host mdarrays
+ * @{
+ */
+
 /**
  * @brief Create a host mdarray.
  * @tparam ElementType the data type of the matrix elements
@@ -90,6 +95,10 @@ auto make_host_mdarray(raft::resources& res, extents<IndexType, Extents...> exts
   return mdarray_t{res, layout, policy};
 }
 
+/**
+ * @}
+ */
+
 /**
  * @brief Create a host mdarray.
  * @tparam ElementType the data type of the matrix elements
@@ -117,6 +126,7 @@ auto make_host_mdarray(extents<IndexType, Extents...> exts)
 }
 
 /**
+ * @ingroup host_mdarray_factories
  * @brief Create a 2-dim c-contiguous host mdarray.
  * @tparam ElementType the data type of the matrix elements
  * @tparam IndexType the index type of the extents
@@ -157,6 +167,7 @@ auto make_host_matrix(IndexType n_rows, IndexType n_cols)
 }
 
 /**
+ * @ingroup host_mdarray_factories
  * @brief Create a host scalar from v.
  *
  * @tparam ElementType the data type of the scalar element
@@ -206,6 +217,7 @@ auto make_host_scalar(ElementType const& v)
 }
 
 /**
+ * @ingroup host_mdarray_factories
  * @brief Create a 1-dim host mdarray.
  * @tparam ElementType the data type of the vector elements
  * @tparam IndexType the index type of the extents

cpp/include/raft/core/host_span.hpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, NVIDIA CORPORATION.
+ * Copyright (c) 2022-2023, NVIDIA CORPORATION.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,10 +19,20 @@
 #include <raft/core/span.hpp>
 
 namespace raft {
+
+/**
+ * @defgroup device_span one-dimensional device span type
+ * @{
+ */
+
 /**
  * @brief A span class for host pointer.
  */
 template <typename T, size_t extent = std::experimental::dynamic_extent>
 using host_span = span<T, false, extent>;
 
+/**
+ * @}
+ */
+
 }  // end namespace raft

cpp/include/raft/core/interruptible.hpp

@@ -30,6 +30,11 @@
 
 namespace raft {
 
+/**
+ * @defgroup interruptible definitions and classes related to the interruptible API
+ * @{
+ */
+
 /**
  * @brief Exception thrown during `interruptible::synchronize` call when it detects a request
  * to cancel the work performed in this CPU thread.
@@ -297,6 +302,10 @@ class interruptible {
   }
 };
 
+/**
+ * @}
+ */
+
 }  // namespace raft
 
 #endif

cpp/include/raft/core/mdarray.hpp

@@ -32,6 +32,12 @@
 #include <raft/core/resources.hpp>
 
 namespace raft {
+
+/**
+ * @defgroup mdarray multi-dimensional memory-owning type
+ * @{
+ */
+
 /**
  * @brief Interface to implement an owning multi-dimensional array
  *
@@ -207,6 +213,7 @@ class mdarray
     : cp_(cp), map_(m), c_(cp_.create(handle, map_.required_span_size()))
   {
   }
+
   RAFT_MDARRAY_CTOR_CONSTEXPR mdarray(raft::resources const& handle,
                                       mapping_type const& m,
                                       container_policy_type& cp)
@@ -336,6 +343,15 @@ class mdarray
   container_type c_;
 };
 
+/**
+ * @}
+ */
+
+/**
+ * @defgroup mdarray_reshape Row- or Col-norm computation
+ * @{
+ */
+
 /**
  * @brief Flatten object implementing raft::array_interface into a 1-dim array view
  *
@@ -371,4 +387,8 @@ auto reshape(const array_interface_type& mda, extents<IndexType, Extents...> new
   return reshape(mda.view(), new_shape);
 }
 
+/**
+ * }@
+ */
+
 }  // namespace raft

cpp/include/raft/core/mdspan.hpp

@@ -213,6 +213,11 @@ constexpr auto make_extents(Extents... exts)
   return extents<IndexType, ((void)exts, dynamic_extent)...>{exts...};
 }
 
+/**
+ * @defgroup mdspan_reshape Row- or Col-norm computation
+ * @{
+ */
+
 /**
  * @brief Flatten raft::mdspan into a 1-dim array view
  *
@@ -298,6 +303,10 @@ RAFT_INLINE_FUNCTION auto unravel_index(Idx idx,
   }
 }
 
+/**
+ * @}
+ */
+
 /**
  * @brief Const accessor specialization for default_accessor
  *

cpp/include/raft/core/span.hpp

@@ -32,6 +32,11 @@
 #include <type_traits>
 
 namespace raft {
+
+/**
+ * @defgroup span one-dimensional span type
+ * @{
+ */
 /**
  * @brief The span class defined in ISO C++20.  Iterator is defined as plain pointer and
  *        most of the methods have bound check on debug build.
@@ -274,4 +279,8 @@ auto as_writable_bytes(span<T, is_device, E> s) noexcept
 {
   return {reinterpret_cast<std::byte*>(s.data()), s.size_bytes()};
 }
+
+/**
+ * @}
+ */
 }  // namespace raft

cpp/include/raft/linalg/normalize.cuh

@@ -26,7 +26,7 @@ namespace raft {
 namespace linalg {
 
 /**
- * @defgroup norm Row- or Col-norm computation
+ * @defgroup normalize Row- or Col-norm computation
  * @{
  */
 

cpp/include/raft/random/rng.cuh

@@ -29,6 +29,11 @@
 
 namespace raft::random {
 
+/**
+ * \defgroup univariate_random_sampling Univariate random sampling
+ * @{
+ */
+
 /**
  * @brief Generate uniformly distributed numbers in the given range
  *
@@ -52,6 +57,10 @@ void uniform(raft::resources const& handle,
     rng_state, out.data_handle(), out.extent(0), start, end, resource::get_cuda_stream(handle));
 }
 
+/**
+ * @}
+ */
+
 /**
  * @brief Legacy overload of `uniform` taking raw pointers
  *
@@ -76,6 +85,7 @@ void uniform(raft::resources const& handle,
 }
 
 /**
+ * @ingroup univariate_random_sampling
  * @brief Generate uniformly distributed integers in the given range
  *
  * @tparam OutputValueType Integral type; value type of the output vector
@@ -128,6 +138,7 @@ void uniformInt(raft::resources const& handle,
 }
 
 /**
+ * @ingroup univariate_random_sampling
  * @brief Generate normal distributed numbers
  *   with a given mean and standard deviation
  *
@@ -175,6 +186,7 @@ void normal(raft::resources const& handle,
 }
 
 /**
+ * @ingroup univariate_random_sampling
  * @brief Generate normal distributed integers
  *
  * @tparam OutputValueType Integral type; value type of the output vector
@@ -228,6 +240,7 @@ void normalInt(raft::resources const& handle,
 }
 
 /**
+ * @ingroup univariate_random_sampling
  * @brief Generate normal distributed table according to the given set of
  * means and scalar standard deviations.
  *
@@ -326,6 +339,7 @@ void normalTable(raft::resources const& handle,
 }
 
 /**
+ * @ingroup univariate_random_sampling
  * @brief Fill a vector with the given value
  *
  * @tparam OutputValueType Value type of the output vector
@@ -364,6 +378,7 @@ void fill(
 }
 
 /**
+ * @ingroup univariate_random_sampling
  * @brief Generate bernoulli distributed boolean array
  *
  * @tparam OutputValueType Type of each element of the output vector;
@@ -407,6 +422,7 @@ void bernoulli(
 }
 
 /**
+ * @ingroup univariate_random_sampling
  * @brief Generate bernoulli distributed array and applies scale
  *
  * @tparam OutputValueType Data type in which to compute the probabilities
@@ -453,6 +469,7 @@ void scaled_bernoulli(raft::resources const& handle,
 }
 
 /**
+ * @ingroup univariate_random_sampling
  * @brief Generate Gumbel distributed random numbers
  *
  * @tparam OutputValueType data type of output random number
@@ -501,6 +518,7 @@ void gumbel(raft::resources const& handle,
 }
 
 /**
+ * @ingroup univariate_random_sampling
  * @brief Generate lognormal distributed numbers
  *
  * @tparam OutputValueType data type of output random number
@@ -547,6 +565,7 @@ void lognormal(raft::resources const& handle,
 }
 
 /**
+ * @ingroup univariate_random_sampling
  * @brief Generate logistic distributed random numbers
  *
  * @tparam OutputValueType data type of output random number
@@ -593,6 +612,7 @@ void logistic(raft::resources const& handle,
 }
 
 /**
+ * @ingroup univariate_random_sampling
  * @brief Generate exponentially distributed random numbers
  *
  * @tparam OutputValueType data type of output random number
@@ -632,6 +652,7 @@ void exponential(
 }
 
 /**
+ * @ingroup univariate_random_sampling
  * @brief Generate rayleigh distributed random numbers
  *
  * @tparam OutputValueType data type of output random number
@@ -670,6 +691,7 @@ void rayleigh(
   detail::rayleigh(rng_state, ptr, len, sigma, resource::get_cuda_stream(handle));
 }
 /**
+ * @ingroup univariate_random_sampling
  * @brief Generate laplace distributed random numbers
  *
  * @tparam OutputValueType data type of output random number
@@ -716,6 +738,7 @@ void laplace(raft::resources const& handle,
 }
 
 /**
+ * @ingroup univariate_random_sampling
  * @brief Generate random integers, where the probability of i is weights[i]/sum(weights)
  *
  * Usage example:

docs/source/cpp_api/core_interruptible.rst

@@ -10,6 +10,7 @@ Interruptible
 
 namespace *raft::core*
 
-.. doxygenclass:: raft::interruptible
-    :project: RAFT
-    :members:
+ .. doxygengroup:: interruptible
+     :project: RAFT
+     :members:
+     :content-only:

docs/source/cpp_api/core_resources.rst

@@ -6,7 +6,7 @@ Resources
    :class: highlight
 
 All resources which are specific to a computing environment like host or device are contained within, and managed by,
-raft::resources. This design simplifies the APIs and eases user burden by making them opaque by default but allowing customization based on user preference.
+`raft::resources`. This design simplifies the APIs and eases user burden by making the APIs opaque by default but allowing customization based on user preference.
 
 
 Vocabulary
@@ -25,6 +25,8 @@ namespace *raft::resource*
 Device Resources
 ----------------
 
+`raft::device_resources` is a convenience over using `raft::resources` directly. It provides accessor methods to retrieve resources such as the CUDA stream, stream pool, and handles to the various CUDA math libraries like cuBLAS and cuSOLVER. 
+
 ``#include <raft/core/device_resources.hpp>``
 
 namespace *raft::core*
@@ -81,7 +83,7 @@ CUDA Stream Pool
 
 namespace *raft::resource*
 
-.. doxygengroup:: resource_cuda_stream_pool
+.. doxygengroup:: resource_stream_pool
     :project: RAFT
     :members:
     :content-only: