docs: Fix sphinx-level warnings (#1430)

This change makes sphinx fail on warnings (it will keep going to the end
though). Also, all warnings are either fixed or ignored with a
expression pattern matching. This is necessary because the way the API
doc works, sphinx will complain about duplicate anchors.

.github/workflows/docs.yml

@@ -18,7 +18,8 @@ jobs:
       - uses: actions/checkout@v2
       - name: Install dependencies
         run: >
-          apt-get install -y doxygen
+          curl -SL https://www.doxygen.nl/files/doxygen-1.9.4.linux.bin.tar.gz | tar -xzC .
+          && mv doxygen-1.9.4/bin/doxygen /usr/local/bin/doxygen
           && pip3 install --upgrade pip
           && pip install -r docs/requirements.txt
       - name: Configure

CMakeLists.txt

@@ -163,7 +163,7 @@ set(_acts_boost_version 1.71.0)
 set(_acts_dd4hep_version 1.21)
 set(_acts_actsdd4hep_version 1.0.0)
 set(_acts_edm4hep_version v00-04-01)
-set(_acts_doxygen_version 1.8.15)
+set(_acts_doxygen_version 1.9.4)
 set(_acts_eigen3_version 3.3.7)
 set(_acts_hepmc3_version 3.2.1)
 set(_acts_nlohmanjson_version 3.2.0)

CONTRIBUTING.rst

@@ -138,9 +138,9 @@ familiar with development process in the Acts project.
    Well-written commit messages are key
    to understand your changes. There are many guidelines available on
    how to write proper commit logs (e.g.
-   `here <http://alistapart.com/article/the-art-of-the-commit>`_,
-   `here <http://chris.beams.io/posts/git-commit/>`_, or
-   `here <https://wiki.openstack.org/wiki/GitCommitMessages#Information_in_commit_messages>`_).
+   `here <http://alistapart.com/article/the-art-of-the-commit>`__,
+   `here <http://chris.beams.io/posts/git-commit/>`__, or
+   `here <https://wiki.openstack.org/wiki/GitCommitMessages#Information_in_commit_messages>`__).
    As a short summary:
 
    -  Structure your commit messages into short title (max 50
@@ -162,15 +162,15 @@ familiar with development process in the Acts project.
    remote repository. These merge commits are considered to contribute
    little information to the development process of the feature and they
    clutter the history (read more e.g.
-   `here <https://developer.atlassian.com/blog/2016/04/stop-foxtrots-now/>`_
+   `here <https://developer.atlassian.com/blog/2016/04/stop-foxtrots-now/>`__
    or
-   `here <http://victorlin.me/posts/2013/09/30/keep-a-readable-git-history>`_).
+   `here <http://victorlin.me/posts/2013/09/30/keep-a-readable-git-history>`__).
    This problem can be avoided by using ``git pull --rebase`` which
    replays your local (un-pushed) commits on the tip of the remote
    branch. You can make this the default behaviour by running
    ``git config pull.rebase true``. More about merging vs rebasing can
    be found
-   `here <https://www.atlassian.com/git/tutorials/merging-vs-rebasing/>`_.
+   `here <https://www.atlassian.com/git/tutorials/merging-vs-rebasing/>`__.
 
 #. **Update the documentation!**
 

Core/include/Acts/Definitions/Units.hpp

@@ -10,79 +10,126 @@
 
 namespace Acts {
 
-/// Unit definitions and conversions.
-///
+/// @verbatim embed:rst:leading-slashes
 /// All physical quantities have both a numerical value and a unit. For the
-/// computations we always choose a particular unit so we only need to consider
-/// the numerical values as such. The chosen base unit for a particular
-/// physical quantity, e.g. length, time, or energy, within this code base
-/// is called the native unit.
+/// computations we always choose a particular unit for a given physical
+/// quantity so we only need to consider the numerical values as such. The
+/// chosen base unit for a particular physical dimension, e.g. length, time, or
+/// energy, within this code base is called the native unit. The base units
+/// should be chosen such that they are internally consistent, require the least
+/// amount of explicit conversion factors (ideally none at all), and have
+/// typical numerical values close to unity to reduce numerical issues.
 ///
 /// Here, the following native units are used:
 ///
-/// *   Length is expressed in mm.
-/// *   Time is expressed in [speed-of-light * time] == mm. A consequence
-///     of this choice is that the speed-of-light expressed in native units
-///     is 1.
-/// *   Angles are expressed in radian.
-/// *   Energy, mass, and momentum are all expressed in GeV (consistent with
-///     a speed-of-light == 1).
-/// *   Electric charge is expressed in e, i.e. units of the elementary charge.
-/// *   The magnetic field is expressed in GeV/(e*mm). The magnetic field
-///     connects momentum to length, e.g. in SI units the radius of a charged
-///     particle trajectory in a constant magnetic field is given by
+/// - Length is expressed in mm.
+/// - Time is expressed in [speed-of-light * time] == mm. A consequence
+///   of this choice is that the speed-of-light expressed in native units
+///   is 1.
+/// - Angles are expressed in radian.
+/// - Energy, mass, and momentum are all expressed in GeV (consistent with
+///   speed-of-light == 1).
+/// - Electric charge is expressed in e, i.e. units of the elementary charge.
+/// - The magnetic field is expressed in GeV/(e*mm). The magnetic field
+///   connects momentum to length, e.g. in SI units the radius of a charged
+///   particle trajectory in a constant magnetic field is given by
+///
+///   .. math::
+///
+///      radius = - (momentum / charge) / field
+///
+///   With the chosen magnetic field unit the expression above stays the
+///   same and no additional conversion factors are necessary.
+/// - Amount of substance is expressed in mol.
+///
+/// Depending on the context a physical quantity might not be given in the
+/// native units. In this case we need to convert to the native unit first
+/// before the value can be used. The necessary conversion factors are defined
+/// in  ``Acts::UnitConstants``. Multiplying a value with the unit constant
+/// produces the equivalent value in the native unit, e.g.
+///
+/// .. code-block:: cpp
+///
+///    double length = 1 * Acts::UnitConstants::m;       // length == 1000.0
+///    double momentum = 100 * Acts::UnitConstants::MeV; // momentum == 0.1
+///
+/// The conversion of a value in native units into the equivalent value in a
+/// specific other unit is computed by dividing with the relevant unit, e.g.
+///
+/// .. code-block:: cpp
 ///
-///         radius = - (momentum / charge) / magnetic-field
+///    double length = 10.0;                               // native units mm
+///    double lengthInM = length / Acts::UnitConstants::m; // == 0.01;
 ///
-///     With the chosen magnetic field unit the expression above stays the
-///     same and no additional conversion factors are necessary.
-/// *   Amount of substance is expressed in mol.
+/// To further simplify the usage, physical quantities can also be expressed via
+/// `C++ user literals
+/// <https://en.cppreference.com/w/cpp/language/user_literal>`_ defined in
+/// ``Acts::UnitLiterals``. This allows us to express quantities in a concise
+/// way:
+///
+/// .. code-block:: cpp
+///
+///    using namespace Acts::UnitLiterals;
+///
+///    double length = 1_m;                     // == 1000.0
+///    double momentum = 1.25_TeV;              // == 1250.0
+///    double lengthInUm = length / 1_um;       // == 1000000.0
+///    double momentumInMeV = momentum / 1_MeV; // == 1250000.0
+///
+/// .. warning::
+///    Since using user-defined literals requires a namespace import of
+///    ``Acts::UnitLiterals`` it should not be used in headers since it would
+///    (accidentally) modify the namespace wherever the header is included.
 ///
 /// To ensure consistent computations and results the following guidelines
 /// **must** be followed when handling physical quantities with units:
 ///
-/// *   All unqualified numerical values, i.e. without a unit, are assumed to
-///     be expressed in the relevant native unit, e.g. mm for lengths or GeV
-///     for energy/momentum.
-/// *   If a variable stores a physical quantity in a specific unit that is
-///     not the native unit, clearly mark this in the variable, i.e.
+/// - All unqualified numerical values, i.e. without a unit, are assumed to
+///   be expressed in the relevant native unit, e.g. mm for lengths or GeV
+///   for energy/momentum.
+/// - If a variable stores a physical quantity in a specific unit that is
+///   not the native unit, clearly mark this in the variable, i.e.
 ///
-///         double momentum = 100.0; // momentum is stored as native unit GeV
-///         double momentumInMeV = 10.0; // would be 0.01 in native units
+///   .. code-block:: cpp
 ///
-/// *   All input values must be given as `numerical_value * unit_constant` or
-///     equivalently using the unit literals as `value_unit`. The resulting
-///     unqualified numerical value will be automatically converted to the
-///     native unit.
-/// *   To output an unqualified numerical value in the native units as a
-///     numerical value in a specific unit divide by the unit constants as
-///     `numerical_value / unit_constant` or using the unit literals as
-///     `value / 1_unit`.
+///      double momentum = 100.0; // momentum is stored as native unit GeV
+///      double momentumInMeV = 10.0; // would be 0.01 in native units
+///
+/// - All input values must be given as ``numerical_value * unit_constant`` or
+///   equivalently using the unit literals as ``value_unit``. The resulting
+///   unqualified numerical value will be automatically converted to the
+///   native unit.
+/// - To output an unqualified numerical value in the native units as a
+///   numerical value in a specific unit divide by the unit constants as
+///   ``numerical_value / unit_constant`` or using the unit literals as
+///   ``value / 1_unit``.
 ///
 /// Examples:
 ///
-///     #include "Acts/include/Definitions/Units.hpp"
-///     using namespace Acts::UnitLiterals;
-///
-///     // define input values w/ units (via unit constants)
-///     double width    = 12 * Acts::UnitConstants::mm;
-///     double mmuon    = 105.7 * Acts::UnitConstants::MeV;
-///     // define input values w/ units (via unit user literals)
-///     double length   = 23_cm;
-///     double time     = 1214.2_ns;
-///     double angle    = 123_degree;
-///     double momentum = 2.5_TeV;
-///     double mass     = 511_keV;
-///     double velocity = 345_m / 1_s;
-///     double bfield   = 3.9_T;
-///     double density  = 1_mol / 1_cm3;
-///
-///     // convert output values (via unit constants)
-///     doube t_in_ns    = trackPars.time() / Acts::UnitConstants::ns;
-///     // convert output values (via unit user literals)
-///     double x_in_mm   = trackPars.position()[ePos0] / 1_mm;
-///     double p_in_TeV = trackPars.absoluteMomentum() / 1_TeV;
+/// .. code-block:: cpp
+///
+///    #include <Acts/include/Definitions/Units.hpp>
+///    using namespace Acts::UnitLiterals;
+///
+///    // define input values w/ units (via unit constants)
+///    double width    = 12 * Acts::UnitConstants::mm;
+///    double mmuon    = 105.7 * Acts::UnitConstants::MeV;
+///    // define input values w/ units (via unit user literals)
+///    double length   = 23_cm;
+///    double time     = 1214.2_ns;
+///    double angle    = 123_degree;
+///    double momentum = 2.5_TeV;
+///    double mass     = 511_keV;
+///    double velocity = 345_m / 1_s;
+///    double bfield   = 3.9_T;
+///
+///    // convert output values (via unit constants)
+///    doube t_in_ns    = trackPars.time() / Acts::UnitConstants::ns;
+///    // convert output values (via unit user literals)
+///    double x_in_mm   = trackPars.position()[ePos0] / 1_mm;
+///    double p_in_TeV = trackPars.absoluteMomentum() / 1_TeV;
 ///
+/// @endverbatim
 
 /// @note A helper script is available in
 ///   `Core/scripts/print_units_physical_constants.py` to validate some of the

Core/include/Acts/EventData/VectorMultiTrajectory.hpp

@@ -16,7 +16,9 @@ namespace Acts {
 
 class VectorMultiTrajectory final
     : public MultiTrajectory<VectorMultiTrajectory> {
+#ifndef DOXYGEN
   friend MultiTrajectory<VectorMultiTrajectory>;
+#endif
 
   struct IndexData {
     IndexType iprevious = kInvalid;

Core/include/Acts/Geometry/BoundarySurfaceT.hpp

@@ -35,8 +35,9 @@ class Surface;
 
 template <class volume_t>
 class BoundarySurfaceT {
-  /// declare the TrackingVolume as friend
+#ifndef DOXYGEN
   friend volume_t;
+#endif
 
   using VolumePtr = std::shared_ptr<const volume_t>;
   using VolumeArray = BinnedArray<VolumePtr>;

Core/include/Acts/Geometry/GeometryContext.hpp

@@ -8,7 +8,7 @@
 
 #pragma once
 
-/// Set the Geometry Context PLUGIN
+// Set the Geometry Context PLUGIN
 #ifdef ACTS_CORE_GEOMETRYCONTEXT_PLUGIN
 #include ACTS_CORE_GEOMETRYCONTEXT_PLUGIN
 #else

Core/include/Acts/MagneticField/BFieldMapUtils.hpp

@@ -18,9 +18,9 @@
 #include <utility>
 #include <vector>
 
-/// Convenience functions to ease creation of and Acts::InterpolatedBFieldMap
-/// and to avoid code duplication. Currently implemented for the two most common
-/// formats: rz and xyz.
+// Convenience functions to ease creation of and Acts::InterpolatedBFieldMap
+// and to avoid code duplication. Currently implemented for the two most common
+// formats: rz and xyz.
 
 namespace Acts {
 

Core/include/Acts/MagneticField/MagneticFieldContext.hpp

@@ -8,7 +8,7 @@
 
 #pragma once
 
-/// Set the Mangetic Field Context PLUGIN
+// Set the Mangetic Field Context PLUGIN
 #ifdef ACTS_CORE_MAGFIELDCONTEXT_PLUGIN
 #include ACTS_CORE_MAGFIELDCONTEXT_PLUGIN
 #else

Core/include/Acts/Material/MaterialMapUtils.hpp

@@ -18,9 +18,9 @@
 #include <functional>
 #include <vector>
 
-/// Convenience functions to ease creation of and Acts::InterpolatedMaterialMap
-/// and to avoid code duplication. Currently implemented for the two most common
-/// formats: rz and xyz.
+// Convenience functions to ease creation of and Acts::InterpolatedMaterialMap
+// and to avoid code duplication. Currently implemented for the two most common
+// formats: rz and xyz.
 
 namespace Acts {
 

Core/include/Acts/Propagator/AbortList.hpp

@@ -21,6 +21,8 @@ namespace hana = boost::hana;
 
 namespace Acts {
 
+/// @cond
+
 /// @brief AbortList object to be used in the propagation
 ///
 /// The abort list is a list of structs or classes that
@@ -115,4 +117,6 @@ struct AbortList : public detail::Extendable<aborters_t...> {
   }
 };
 
-}  // namespace Acts
+/// @endcond
+
+}  // namespace Acts

Core/include/Acts/Propagator/ActionList.hpp

@@ -22,6 +22,8 @@ namespace hana = boost::hana;
 
 namespace Acts {
 
+/// @cond
+
 /// @brief ActionList implementation to be used with the propagator
 ///
 /// This is the ActionList struct that is used in the propagator
@@ -83,7 +85,7 @@ struct ActionList : public detail::Extendable<actors_t...> {
   void operator()(propagator_state_t& state, const stepper_t& stepper,
                   result_t& result) const {
     // clang-format off
-    static_assert(detail::all_of_v<detail::action_signature_check_v<actors_t, 
+    static_assert(detail::all_of_v<detail::action_signature_check_v<actors_t,
                                       propagator_state_t, stepper_t>...>,
                   "not all actors support the method signature");
     // clang-format on
@@ -93,4 +95,6 @@ struct ActionList : public detail::Extendable<actors_t...> {
   }
 };
 
-}  // namespace Acts
+/// @endcond
+
+}  // namespace Acts

Core/include/Acts/Propagator/EigenStepper.hpp

@@ -384,14 +384,11 @@ class EigenStepper {
 
   /// Perform a Runge-Kutta track parameter propagation step
   ///
-  /// @param [in,out] state is the propagation state associated with the track
-  /// parameters that are being propagated.
-  ///
-  ///                      the state contains the desired step size.
-  ///                      It can be negative during backwards track
-  ///                      propagation,
-  ///                      and since we're using an adaptive algorithm, it can
-  ///                      be modified by the stepper class during propagation.
+  /// @param [in,out] state is the propagation
+  /// @note The state contains the desired step size.  It can be negative during
+  ///       backwards track propagation, and since we're using an adaptive
+  ///       algorithm, it can be modified by the stepper class during
+  ///       propagation.
   template <typename propagator_state_t>
   Result<double> step(propagator_state_t& state) const;
 

Core/include/Acts/Seeding/Seedfinder.hpp

@@ -110,4 +110,6 @@ class Seedfinder {
 
 }  // namespace Acts
 
+#ifndef DOXYGEN
 #include "Acts/Seeding/Seedfinder.ipp"
+#endif

Core/include/Acts/Surfaces/ConeSurface.hpp

@@ -30,7 +30,9 @@ namespace Acts {
 /// curvilinear coordinates.
 
 class ConeSurface : public Surface {
+#ifndef DOXYGEN
   friend Surface;
+#endif
 
  protected:
   /// Constructor form HepTransform and an opening angle

Core/include/Acts/Surfaces/CylinderSurface.hpp

@@ -31,7 +31,9 @@ namespace Acts {
 /// @image html CylinderSurface.png
 
 class CylinderSurface : public Surface {
+#ifndef DOXYGEN
   friend Surface;
+#endif
 
  protected:
   /// Constructor from DetectorElementBase: Element proxy