docs: Restructure and update the documentation - 2023 edition

[paulgessinger]

This PR rationalizes the documentation a bit. The main points are

• Remove the documentation of the old standalone examples executables

• Restructure the core documentation to be less sprawling

• Move the figures from a central folder closer to the relevant source files

• Remove the full auto API documentation in favor of a combination of hard-coded documented symbols + an auto detection mechanism to catch when we references symbols somewhere

  • This reduces the time it takes to build the docs drastically

• Enable nitpicky generation, which will warn (and fail) if symbols are references that don't have a target.

• Try to auto-generate API listings only for the elements we explicitly call out by class / func roles.

Blocked by:

• refactor!: Move Grid out of detail #2616
• refactor: Remove separate default DetectorElementBase file #2617
• refactor: Use std::size_t consistently #2624

[github-actions]

📊: Physics performance monitoring for bdd1475

Full contents

physmon summary

• ✅ CKF truth_smeared
• ✅ IVF truth_smeared
• ✅ AMVF truth_smeared
• ✅ Track Summary CKF truth_smeared
• ✅ Seeding truth_estimated
• ✅ CKF truth_estimated
• ✅ IVF truth_estimated
• ✅ AMVF truth_estimated
• ✅ Track Summary CKF truth_estimated
• ✅ Seeding seeded
• ✅ CKF seeded
• ✅ IVF seeded
• ✅ AMVF seeded
• ✅ AMVF (+grid seeder) seeded
• ✅ Track Summary CKF seeded
• ✅ Seeding orthogonal
• ✅ CKF orthogonal
• ✅ IVF orthogonal
• ✅ AMVF orthogonal
• ✅ Track Summary CKF orthogonal
• ✅ Ambisolver seeded
• ✅ Ambisolver orthogonal
• ✅ Seeding ttbar
• ✅ CKF ttbar
• ✅ Ambisolver
• ✅ Track Summary CKF ttbar
• ✅ AMVF ttbar
• ✅ AMVF (+grid seeder) ttbar
• ✅ Truth tracking (GSF)
• ✅ Truth tracking
• ✅ Particles inital fatras
• ✅ Particles final fatras
• ✅ Particles inital geant4
• ✅ Particles final geant4

[codecov]

Codecov Report

Merging #2610 (bdd1475) into main (7529e62) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##             main    #2610   +/-   ##
=======================================
  Coverage   49.59%   49.59%           
=======================================
  Files         473      473           
  Lines       26824    26824           
  Branches    12355    12355           
=======================================
  Hits        13304    13304           
  Misses       4753     4753           
  Partials     8767     8767           

Files	Coverage Δ
Core/include/Acts/Propagator/AbortList.hpp	83.33% <ø> (ø)
Core/include/Acts/Propagator/ActionList.hpp	100.00% <ø> (ø)
Core/include/Acts/Propagator/ConstrainedStep.hpp	68.88% <ø> (ø)
Core/include/Acts/Surfaces/ConeBounds.hpp	71.42% <ø> (ø)
Core/include/Acts/Surfaces/CylinderBounds.hpp	68.75% <ø> (ø)
Core/include/Acts/Surfaces/CylinderSurface.hpp	100.00% <ø> (ø)
Core/include/Acts/Surfaces/DiamondBounds.hpp	62.50% <ø> (ø)
Core/include/Acts/Surfaces/DiscSurface.hpp	100.00% <ø> (ø)
Core/include/Acts/Surfaces/EllipseBounds.hpp	62.96% <ø> (ø)
Core/include/Acts/Surfaces/LineSurface.hpp	100.00% <ø> (ø)
... and 5 more

📣 Codecov offers a browser extension for seamless coverage viewing on GitHub. Try it in Chrome or Firefox today!

[AJPfleger]

Maybe you could mention in the description, that you removed some of the examples.

Invalidated by push of 23787a6

[paulgessinger]

@AJPfleger can you click the button again? I've updated this after #2591 was merged.

[acts-project-service]

✅ Athena integration test results [922e6d1]

✅ All tests successful

status	job
🟢	run_unit_tests
🟢	run_ci_tests: ../athena/AtlasTest/CITest/test/ActsBenchmarkWithSpot.sh 8 100
🟢	run_ci_tests: ../athena/AtlasTest/CITest/test/ActsWorkflow.sh
🟢	run_ci_tests: ../athena/AtlasTest/CITest/test/ActsValidateAmbiguityResolution.sh
🟢	run_ci_tests: ../athena/AtlasTest/CITest/test/ActsValidateTracks.sh
🟢	run_ci_tests: ../athena/AtlasTest/CITest/test/ActsValidateActsCoreSpacePoints.sh
🟢	run_ci_tests: ../athena/AtlasTest/CITest/test/ActsValidateActsSpacePoints.sh
🟢	run_ci_tests: ../athena/AtlasTest/CITest/test/ActsValidateSeeds.sh
🟢	run_ci_tests: ../athena/AtlasTest/CITest/test/ActsValidateOrthogonalSeeds.sh
🟢	run_ci_tests: ../athena/AtlasTest/CITest/test/ActsValidateClusters.sh
🟢	run_ci_tests: ../athena/AtlasTest/CITest/test/ActsPersistifyEDM.sh
🟢	run_ci_tests: ../athena/AtlasTest/CITest/test/ActsKfRefitting.sh
🟢	run_ci_tests: python3 ../athena/Tracking/Acts/ActsGeometry/test/ActsExtrapolationAlgTest.py
🟢	run_ci_tests: python3 ../athena/Tracking/Acts/ActsGeometry/test/ActsITkTest.py
🟢	run_workflow_tests_run4_mc
🟢	run_workflow_tests_run2_data
🟢	run_workflow_tests_run3_mc
🟢	run_workflow_tests_run3_data