Enable warning as errors when building docs

.github/workflows/ci_pipeline.yml

@@ -41,7 +41,6 @@ jobs:
           pre-commit run --all-files --verbose --show-diff-on-failure
 
   build-docs:
-    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
     runs-on: ubuntu-22.04
     env:
       REPOSITORY_CHECKOUT_PATH: ${{ github.workspace }}/repository
@@ -65,7 +64,8 @@ jobs:
         working-directory: ${{ env.REPOSITORY_CHECKOUT_PATH }}
         run: beluga/docs/generate_docs.sh
 
-      - name: Deploy documentation
+      - if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        name: Deploy documentation
         working-directory: ${{ env.DOXYGEN_HTML_OUTPUT }}
         env:
           COMMIT_MESSAGE: "Triggered by commit ${{ github.sha }}."

beluga/docs/Doxyfile

@@ -9,5 +9,4 @@ GENERATE_LATEX         = NO
 HTML_OUTPUT            = $(DOXYGEN_HTML_OUTPUT)
 HTML_EXTRA_STYLESHEET  = ./doxygen_extra.css
 CITE_BIB_FILES         = ./doxygen_cites.bib
-# TODO(nahuel): Reenable this when there are no warnings.
-WARN_AS_ERROR          = NO
+WARN_AS_ERROR          = YES

beluga/include/beluga/algorithm/particle_filter.hpp

@@ -45,18 +45,18 @@
  * - A possibly const instance `cp` of `T`.
  *
  * The following is satisfied:
- * - `particle_traits<T>::state_type` is a valid type.
- * - `particle_traits<T>::state(cp)` returns an instance of `particle_traits<T>::state_type`.
- * - Given `s` an instance of `particle_traits<T>::state_type`, `particle_traits<T>::state(p) = s`
- *   is a valid expression and assigns the state `s` to the particle `p`.
- *   i.e. after the assignment `s == particle_traits<T>::state(p)` is `true`.
- * - `particle_traits<T>::weight_type` is a valid arithmetic type (that is, an integral
+ * - \c particle_traits<T>::state_type is a valid type.
+ * - \c particle_traits<T>::state(cp) returns an instance of \c particle_traits<T>::state_type.
+ * - Given `s` an instance of \c particle_traits<T>::state_type, \c particle_traits<T>::state(p) = `s`
+ *   is a valid expression and assigns the state `s` to the particle `p`. \n
+ *   i.e. after the assignment `s` == \c particle_traits<T>::state(p) is `true`.
+ * - \c particle_traits<T>::weight_type is a valid arithmetic type (that is, an integral
  *   type or a floating-point type).
- * - `particle_traits<T>::weight(cp)` is a valid expression and the return type is
- *   `particle_traits<T>::weight_type`.
- * - Given `w` an instance of `particle_traits<T>::weight_type`, `particle_traits<T>::weight(p) = w`
- *   is a valid expression and assigns the weight `w` to the particle `p`.
- *   i.e. after the assignment `w == particle_traits<T>::weight(p)` is `true`.
+ * - \c particle_traits<T>::weight(cp) is a valid expression and the return type is
+ *   \c particle_traits<T>::weight_type.
+ * - Given `w` an instance of \c particle_traits<T>::weight_type, \c particle_traits<T>::weight(p) = `w`
+ *   is a valid expression and assigns the weight `w` to the particle `p`. \n
+ *   i.e. after the assignment `w` == \c particle_traits<T>::weight(p) is `true`.
  */
 
 /**
@@ -113,13 +113,14 @@ namespace beluga {
  * BootstrapParticleFilter<Mixin, Container> is an implementation of the
  * \ref BaseParticleFilterPage "BaseParticleFilter" named requirements.
  *
- * `particle_traits<typename Container::value_type>::state_type` must be the same as
- * the state_type of the sensor and motion model.
+ * Given `T`, the type named by \c Container::value_type,
+ * - \c particle_traits<T>::state_type must be the same as the `state_type` of the sensor
+ *   and motion model.
  *
- * `particle_traits<typename Container::value_type>::weight_type` must be the same as the weight
- * type used in the sensor mode.
+ * - \c particle_traits<T>::weight_type must be the same as the `weight_type` used in the
+ *   sensor mode.
  *
- * \tparam The mixed-in type. An instance m of Mixin must provide a protected method,
+ * \tparam Mixin The mixed-in type. An instance m of Mixin must provide a protected method,
  *  `m.self()`. The return type of `m.self()` must satisfy:
  * - \ref ParticleResamplingPage "ParticleResampling"
  * - \ref ParticleBaselineGenerationPage "ParticleBaselineGeneration"

beluga/include/beluga/algorithm/sampling.hpp

@@ -176,11 +176,11 @@ inline auto set_cluster(double resolution) {
  * \param z Upper standard normal quantile for the probability that the error in the
  *  estimated distribution is less than epsilon.
  * \return A callable object with prototype (std::size_t hash) -> bool.
- *  hash is the spatial hash of the particle being added.
+ *  hash is the spatial hash of the particle being added. \n
  *  The returned callable object is stateful, tracking the total number of particles and
- *  the particle clusters based on the spatial hash.
- *  The return value will be false when the number of particles is more than the minimum
- *  and the kld condition is satisfied, if not it will be true.
+ *  the particle clusters based on the spatial hash. \n
+ *  The return value of the callable will be false when the number of particles is more than the minimum
+ *  and the kld condition is satisfied, if not it will be true. \n
  *  i.e. A return value of true means that you need to keep sampling to satisfy the condition.
  */
 inline auto kld_condition(std::size_t min, double epsilon, double z = 3.) {
@@ -473,11 +473,11 @@ struct KldResampling : public Mixin {
    * It can only be composed with a range whose value type satisfies:
    * - The \ref ParticlePage "Particle" named requirements.
    * - Given `P` the range value type, `p` an instance of `P`, `cp` a possibly const instance of `P`.
-   *   The expression `particle_traits<P>::cluster(cp)` returns a `std::size_t` that represents the spatial
-   *   hash of the particle `cp`.
-   *   Given a `std::size_t` hash, the expression `particle_traits<P>::cluster(p) = hash` is valid and
-   *   assigns the cluster hash to the particle `p`.
-   *   i.e. after the assignment `hash == particle_traits<P>::cluster(p)` is `true`.
+   *   - The expression \c particle_traits<P>::cluster(cp) returns a `std::size_t` that represents the spatial
+   *     hash of the particle `cp`.
+   *   - Given a `std::size_t` hash, the expression \c particle_traits<P>::cluster(p) = hash is valid and
+   *     assigns the cluster hash to the particle `p`. \n
+   *     i.e. after the assignment hash == \c particle_traits<P>::cluster(p) is `true`.
    */
   [[nodiscard]] auto take_samples() const {
     return ranges::views::transform(set_cluster(parameters_.spatial_resolution)) |

beluga/include/beluga/type_traits/particle_traits.hpp

@@ -42,7 +42,7 @@ struct decay_tuple_types<Tuple<Types...>> {
   using type = Tuple<std::decay_t<Types>...>;
 };
 
-/// Same as `decay_tuple_types<T>::type`.
+/// Same as decay_tuple_types<T>::type.
 template <class T>
 using decay_tuple_types_t = typename decay_tuple_types<T>::type;
 
@@ -53,7 +53,7 @@ struct decay_tuple {
   using type = decay_tuple_types_t<std::decay_t<T>>;
 };
 
-/// Same as `decay_tuple<T>::type`.
+/// Same as decay_tuple<T>::type.
 template <class T>
 using decay_tuple_t = typename decay_tuple<T>::type;
 
@@ -243,7 +243,7 @@ constexpr auto clusters(Container&& container) {
 /**
  * \tparam Particle The particle type to be used.
  * \tparam T The particle state type.
- *  T must be convertible to `particle_traits<Particle>::state_type`.
+ *  T must be convertible to \c particle_traits<Particle>::state_type.
  * \param value The state to make the particle from.
  * \return The new particle, created from the given state.
  */