Merge branch 'main' into fix-white-paper-path

acts-project · Nov 7, 2023 · cfa9ef6 · cfa9ef6
2 parents 2ad02b4 + 922e6d1
commit cfa9ef6
Show file tree

Hide file tree

Showing 175 changed files with 1,073 additions and 1,743 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -15,21 +15,43 @@ concurrency:
 jobs:
   docs:
     runs-on: ubuntu-latest
-    container: ghcr.io/acts-project/ubuntu2204:v41
     env:
         DOXYGEN_WARN_AS_ERROR: FAIL_ON_WARNINGS
+        DOXYGEN_VERSION: 1.9.4
     steps:
       - uses: actions/checkout@v3
+
+      - name: Cache doxygen
+        id: cache-doxygen
+        uses: actions/cache@v3
+        with:
+          path: /usr/local/bin/doxygen
+          key: doxygen_${{ env.DOXYGEN_VERSION }}
+
+      - name: Install doxygen
+        if: steps.cache-doxygen.outputs.cache-hit != 'true'
+        run: >
+          curl -SL https://sourceforge.net/projects/doxygen/files/rel-${{ env.DOXYGEN_VERSION }}/doxygen-${{ env.DOXYGEN_VERSION }}.linux.bin.tar.gz/download | tar -xzC .
+          && mv doxygen-${{ env.DOXYGEN_VERSION }}/bin/doxygen /usr/local/bin/doxygen
+
       - name: Install dependencies
         run: >
-          curl -SL https://sourceforge.net/projects/doxygen/files/rel-1.9.4/doxygen-1.9.4.linux.bin.tar.gz/download | tar -xzC .
-          && mv doxygen-1.9.4/bin/doxygen /usr/local/bin/doxygen
-          && pip3 install --upgrade pip
+          pip3 install --upgrade pip
           && pip install -r docs/requirements.txt
-      - name: Configure
-        run: cmake -B build -S . -GNinja -DACTS_BUILD_DOCS=ON
-      - name: Build
-        run: cmake --build build --target docs-with-api
+
+      - name: Build documentation
+        run: >
+          cd docs
+          && sphinx-build
+          -b html
+          -d _build/doctrees/
+          -j auto
+          -W
+          --keep-going
+          -t run_doxygen
+          -b linkcheck
+          . _build/html/
+
       - uses: actions/upload-artifact@v3
         with:
           name: acts-docs

diff --git a/Core/include/Acts/Definitions/Algebra.hpp b/Core/include/Acts/Definitions/Algebra.hpp
@@ -42,7 +42,6 @@ namespace Acts {
 /// no dynamic-sized symmetric matrix type is defined. Use the
 /// `ActsDynamicMatrix` instead.
 ///
-/// @{
 
 /// Common scalar (floating point type used for the default algebra types.
 ///
@@ -67,15 +66,12 @@ using ActsDynamicVector = Eigen::Matrix<ActsScalar, Eigen::Dynamic, 1>;
 using ActsDynamicMatrix =
     Eigen::Matrix<ActsScalar, Eigen::Dynamic, Eigen::Dynamic>;
 
-/// @}
-
 /// @defgroup coordinates-types Fixed-size vector/matrix types for coordinates
 ///
 /// These predefined types should always be used when handling coordinate
 /// vectors in different coordinate systems, i.e. on surfaces (2d), spatial
 /// position (3d), or space-time (4d).
 ///
-/// @{
 
 // coordinate vectors
 using Vector2 = ActsVector<2>;
@@ -104,6 +100,4 @@ using AngleAxis3 = Eigen::AngleAxis<ActsScalar>;
 using Transform2 = Eigen::Transform<ActsScalar, 2, Eigen::AffineCompact>;
 using Transform3 = Eigen::Transform<ActsScalar, 3, Eigen::Affine>;
 
-/// @}
-
 }  // namespace Acts
diff --git a/Core/include/Acts/Propagator/AbortList.hpp b/Core/include/Acts/Propagator/AbortList.hpp
@@ -20,8 +20,6 @@ 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
@@ -39,10 +37,12 @@ struct AbortList : public detail::Extendable<aborters_t...> {
   using detail::Extendable<aborters_t...>::tuple;
 
  public:
+  /// @cond
   // This uses the type collector
   using result_type = typename decltype(hana::unpack(
       detail::type_collector_t<detail::action_type_extractor, aborters_t...>,
       hana::template_<AbortList>))::type;
+  /// @endcond
 
   using detail::Extendable<aborters_t...>::get;
 
@@ -103,6 +103,7 @@ struct AbortList : public detail::Extendable<aborters_t...> {
   /// @param [in] stepper Stepper used for the propagation
   /// @param [in] navigator Navigator used for the propagation
   /// @param [in] result is the result object from a certain action
+  /// @param [in] args are the arguments to be passed to the aborters
   template <typename propagator_state_t, typename stepper_t,
             typename navigator_t, typename result_t, typename... Args>
   bool operator()(propagator_state_t& state, const stepper_t& stepper,
@@ -114,6 +115,4 @@ struct AbortList : public detail::Extendable<aborters_t...> {
   }
 };
 
-/// @endcond
-
 }  // namespace Acts
diff --git a/Core/include/Acts/Propagator/ActionList.hpp b/Core/include/Acts/Propagator/ActionList.hpp
@@ -21,8 +21,6 @@ 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
@@ -37,11 +35,13 @@ struct ActionList : public detail::Extendable<actors_t...> {
   using detail::Extendable<actors_t...>::tuple;
 
  public:
+  /// @cond
   // This uses the type collector and unpacks using the `R` meta function
   template <template <typename...> class R>
   using result_type = typename decltype(hana::unpack(
       detail::type_collector_t<detail::result_type_extractor, actors_t...>,
       hana::template_<R>))::type;
+  /// @endcond
 
   using detail::Extendable<actors_t...>::get;
 
@@ -82,6 +82,7 @@ struct ActionList : public detail::Extendable<actors_t...> {
   /// @param [in] stepper The stepper in use
   /// @param [in] navigator The navigator in use
   /// @param [in,out] result This is the result object from actions
+  /// @param [in] args The arguments to be passed to the actions
   template <typename propagator_state_t, typename stepper_t,
             typename navigator_t, typename result_t, typename... Args>
   void operator()(propagator_state_t& state, const stepper_t& stepper,
@@ -93,6 +94,4 @@ struct ActionList : public detail::Extendable<actors_t...> {
   }
 };
 
-/// @endcond
-
 }  // namespace Acts
diff --git a/Core/include/Acts/Propagator/ConstrainedStep.hpp b/Core/include/Acts/Propagator/ConstrainedStep.hpp
@@ -97,8 +97,6 @@ class ConstrainedStep {
   constexpr Scalar value(Type type) const { return m_values[type]; }
 
   /// Access the accuracy value
-  ///
-  /// @param type is the requested parameter type
   constexpr Scalar accuracy() const { return m_accuracy; }
 
   /// release a certain constraint value
@@ -107,8 +105,6 @@ class ConstrainedStep {
   constexpr void release(Type type) { m_values[type] = kNotSet; }
 
   /// release accuracy
-  ///
-  /// @param type is the constraint type to be released
   constexpr void releaseAccuracy() { m_accuracy = kNotSet; }
 
   /// Update the step size of a certain type

diff --git a/Core/include/Acts/Surfaces/ConeBounds.hpp b/Core/include/Acts/Surfaces/ConeBounds.hpp
@@ -31,7 +31,7 @@ namespace Acts {
 ///  The cone can open to both sides, steered by \f$ z_min \f$ and \f$ z_max
 ///  \f$.
 ///
-///  @image html figures/ConeBounds.gif
+///  @image html ConeBounds.gif
 ///
 
 class ConeBounds : public SurfaceBounds {

diff --git a/Core/include/Acts/Surfaces/CylinderBounds.hpp b/Core/include/Acts/Surfaces/CylinderBounds.hpp
@@ -24,6 +24,7 @@
 namespace Acts {
 
 /// @class CylinderBounds
+/// @image html CylinderBounds.gif
 ///
 /// Bounds for a cylindrical Surface.
 ///

diff --git a/Core/include/Acts/Surfaces/CylinderSurface.hpp b/Core/include/Acts/Surfaces/CylinderSurface.hpp
@@ -38,7 +38,7 @@ class DetectorElementBase;
 /// since it builds the surfaces of all TrackingVolumes at container level
 /// for a cylindrical tracking geometry.
 ///
-/// @image html figures/CylinderSurface.png
+/// @image html CylinderSurface.png
 
 class CylinderSurface : public Surface {
 #ifndef DOXYGEN

diff --git a/Core/include/Acts/Surfaces/DiamondBounds.hpp b/Core/include/Acts/Surfaces/DiamondBounds.hpp
@@ -26,6 +26,7 @@ namespace Acts {
 
 /// @class DiamondBounds
 ///
+/// @image html DiamondBounds.svg
 /// Bounds for a double trapezoidal ("diamond"), planar Surface.
 class DiamondBounds : public PlanarBounds {
  public:

diff --git a/Core/include/Acts/Surfaces/DiscBounds.hpp b/Core/include/Acts/Surfaces/DiscBounds.hpp
@@ -14,6 +14,8 @@ namespace Acts {
 
 /// @class DiscBounds
 ///
+/// @image html DiscBounds.gif
+///
 /// common base class for all bounds that are in a r/phi frame
 ///  - simply introduced to avoid wrong bound assignments to surfaces
 

diff --git a/Core/include/Acts/Surfaces/DiscSurface.hpp b/Core/include/Acts/Surfaces/DiscSurface.hpp
@@ -48,7 +48,7 @@ class SurfaceBounds;
 /// to happen to transfer the local coordinates onto the
 /// cartesian reference frame coordinates.
 ///
-/// @image html figures/DiscSurface.png
+/// @image html DiscSurface.png
 ///
 class DiscSurface : public Surface {
 #ifndef DOXYGEN

diff --git a/Core/include/Acts/Surfaces/EllipseBounds.hpp b/Core/include/Acts/Surfaces/EllipseBounds.hpp
@@ -27,6 +27,8 @@ namespace Acts {
 
 /// @class EllipseBounds
 ///
+/// @image html EllipseBounds.png
+///
 /// Class to describe the bounds for a planar ellispoid
 /// surface.
 ///

diff --git a/Core/include/Acts/Surfaces/LineSurface.hpp b/Core/include/Acts/Surfaces/LineSurface.hpp
@@ -37,7 +37,7 @@ class SurfaceBounds;
 ///
 ///  @note It leaves the type() method virtual, so it can not be instantiated
 ///
-/// @image html figures/LineSurface.png
+/// @image html LineSurface.png
 class LineSurface : public Surface {
 #ifndef DOXYGEN
   friend Surface;
@@ -182,7 +182,7 @@ class LineSurface : public Surface {
   /// of @f$ \vec{d} @f$ on @f$ \vec{measX} @f$:<br> @f$ sign = -sign(\vec{d}
   /// \cdot \vec{measX}) @f$
   ///
-  /// @image html figures/SignOfDriftCircleD0.gif
+  /// @image html SignOfDriftCircleD0.gif
   ///
   /// @param gctx The current geometry context object, e.g. alignment
   /// @param position global 3D position - considered to be on surface but not

diff --git a/Core/include/Acts/Surfaces/PerigeeSurface.hpp b/Core/include/Acts/Surfaces/PerigeeSurface.hpp
@@ -26,7 +26,7 @@ namespace Acts {
 /// The Surface axis is fixed to be the z-axis of the Tracking frame.
 /// It inherits from StraingLineSurface.
 ///
-/// @image html figures/LineSurface.png
+/// @image html LineSurface.png
 class PerigeeSurface : public LineSurface {
 #ifndef DOXYGEN
   friend Surface;

diff --git a/Core/include/Acts/Surfaces/PlaneSurface.hpp b/Core/include/Acts/Surfaces/PlaneSurface.hpp
@@ -37,12 +37,10 @@ class SurfaceBounds;
 /// The PlaneSurface extends the Surface class with the possibility to
 /// convert local to global positions (vice versa).
 ///
-/// @image html figures/PlaneSurface.png
+/// @image html PlaneSurface.png
 ///
 class PlaneSurface : public Surface {
-#ifndef DOXYGEN
-  friend Surface;
-#endif
+  friend class Surface;
 
  protected:
   /// Copy Constructor

diff --git a/Core/include/Acts/Surfaces/RectangleBounds.hpp b/Core/include/Acts/Surfaces/RectangleBounds.hpp
@@ -24,6 +24,8 @@ namespace Acts {
 
 /// @class RectangleBounds
 ///
+/// @image html RectangleBounds.gif
+///
 /// Bounds for a rectangular, planar surface - it can be used to for
 /// rectangles that are symmetrically centered around (0./0.) and for
 /// generic shifted rectangles

diff --git a/Core/include/Acts/Surfaces/StrawSurface.hpp b/Core/include/Acts/Surfaces/StrawSurface.hpp
@@ -29,12 +29,10 @@ class LineBounds;
 ///  Class for a StrawSurface in the TrackingGeometry
 ///  to describe dirft tube and straw like detectors.
 ///
-/// @image html figures/LineSurface.png
+/// @image html LineSurface.png
 ///
 class StrawSurface : public LineSurface {
-#ifndef DOXYGEN
-  friend Surface;
-#endif
+  friend class Surface;
 
  protected:
   /// Constructor from Transform3 and bounds

diff --git a/Core/include/Acts/Surfaces/TrapezoidBounds.hpp b/Core/include/Acts/Surfaces/TrapezoidBounds.hpp
@@ -27,7 +27,7 @@ namespace Acts {
 ///
 /// Bounds for a trapezoidal, planar Surface.
 ///
-/// @image html figures/TrapezoidBounds.gif
+/// @image html TrapezoidBounds.gif
 ///
 /// @todo can be speed optimized by calculating kappa/delta and caching it
 

diff --git a/Examples/Python/setup.sh.in b/Examples/Python/setup.sh.in
@@ -25,6 +25,7 @@ export PYTHONPATH=$python_dir:$PYTHONPATH
 
 # Make ODD available if possible
 # This seems to be only reliable on Linux for now, not on MacOS
+odd_dir=$python_dir/../thirdparty/OpenDataDetector/factory
 if [ -d "$odd_dir" ]; then
     if [[ "$(uname -s)" == "Linux" ]]; then
         echo "INFO:    Found OpenDataDetector and set it up"

diff --git a/Plugins/Geant4/include/Acts/Plugins/Geant4/Geant4DetectorElement.hpp b/Plugins/Geant4/include/Acts/Plugins/Geant4/Geant4DetectorElement.hpp
@@ -32,9 +32,10 @@ class Geant4DetectorElement : public DetectorElementBase {
   using ContextType = GeometryContext;
 
   /// @brief  Constructor with arguments
-  /// @param thickness the thickness of this detector element
+  /// @param surface the surface representing this detector element
+  /// @param g4physVol the physical volume representing this detector element
   /// @param toGlobal the global transformation before the volume
-  /// @param g4phys the physical volume representing this detector element
+  /// @param thickness the thickness of this detector element
   Geant4DetectorElement(std::shared_ptr<Surface> surface,
                         const G4VPhysicalVolume& g4physVol,
                         const Transform3& toGlobal, ActsScalar thickness);

diff --git a/Plugins/Geant4/include/Acts/Plugins/Geant4/Geant4DetectorSurfaceFactory.hpp b/Plugins/Geant4/include/Acts/Plugins/Geant4/Geant4DetectorSurfaceFactory.hpp
@@ -76,16 +76,14 @@ class Geant4DetectorSurfaceFactory {
   };
 
   /// The Geant4 detector element factory
-  ///
-  /// @param cfg the configuration struct
   Geant4DetectorSurfaceFactory() = default;
 
   /// Construction method of the detector elements
   ///
   /// @param cache [in,out] into which the Elements are filled
   /// @param g4ToGlobal the transformation to global
-  /// @param g4PhyVol the current physical volume
-  /// @param options the factory creation option
+  /// @param g4PhysVol the current physical volume
+  /// @param option the factory creation option
   ///
   void construct(Cache& cache, const G4Transform3D& g4ToGlobal,
                  const G4VPhysicalVolume& g4PhysVol, const Options& option);