Documentation using Sphinx+Exhale+Doxygen (revised) (acts-project#197)

* cmake: add FindSphinx

* cmake: doc requires sphinx

* doc: doxygen builds only xml

* doc: build w/ Sphinx

* doc: add layout and move existing content

* doc: build full api doc with exhale

* doc: do not build doxygen html

* doc: add authors and license

* doc: update logo

* doc: import modules and integration content

* doc: simplify navbar

* doc: add unit documentation

* doc: move utilities into sub-folder

* doc: fixes to units

* doc: adjust doc cmakelists

* cmake: split doc generation into separate commands

* doc: update some paths

* doc: update doxygen config

* doc: update requirements

* move the getting started guide to docs

* doc: remove doxygen layout

* doc: simplify cmake config

* doc: reorganize files

* move docs

* doc: add pip requirements file

* cmake: add run-doxygen debug target

* docs: update Doxygen config

* docs: import truth tracking howto from framework

* docs: use consistent rst format

* docs: re-use AUTHORS file

* Update docs/core/material.rst

Co-authored-by: Paul Gessinger <hello@paulgessinger.com>

* docs: add filesystem to boost packages

* move authors to docs

* ci: add docs build job

* gitignore: do not ignore github configs

* docs: always enable doxygen on RTD

* docs: exclude build directory

* add readthedocs config

* Examples: minor README fixes

* Fatras: minor README fixes

* thirdparty: consistent README formatting

* docs: streamline index text

* streamline README

Co-authored-by: Paul Gessinger <hello@paulgessinger.com>

.github/workflows/builds.yml

@@ -88,3 +88,20 @@ jobs:
         run: source ${SETUP} && cmake --build build -- test
       - name: Integration tests
         run: source ${SETUP} && cmake --build build -- integrationtests
+  docs:
+    runs-on: ubuntu-latest
+    container: gitlab-registry.cern.ch/acts/machines/ubuntu2004:master
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install dependencies
+        run: >
+          apt-get install -y doxygen
+          && pip3 install -r docs/requirements.txt
+      - name: Configure
+        run: cmake -B build -S . -GNinja -DACTS_BUILD_DOCS=on
+      - name: Build
+        run: cmake --build build -- docs
+      - uses: actions/upload-artifact@v2
+        with:
+          name: acts-docs
+          path: docs/_build/html/

.gitignore

@@ -36,6 +36,7 @@ build*
 
 # dont ignore hidden configs
 !.clang-format
+!.github/
 !.gitignore
 !.gitlab-ci.yml
 !.clang-tidy

AUTHORS.md → AUTHORS

@@ -1,8 +1,9 @@
-# Contributors to Acts in alphabetical order:
+The following people have contributed to the project (in alphabetical order):
 
 - Andreas Salzburger, CERN
 - Bastian Schlag, CERN, JGU Mainz
 - Christian Gumpert
+- Corentin Allaire, CERN
 - Fabian Klimpel, Max-Planck-Institut für Physik
 - Hadrien Grasland, Centre National de la Recherche Scientifique
 - Julia Hrdinka

CMakeLists.txt

@@ -39,7 +39,7 @@ option(ACTS_BUILD_UNITTESTS "Build unit tests" OFF)
 option(ACTS_BUILD_INTEGRATIONTESTS "Build integration tests" OFF)
 # other options
 option(ACTS_BUILD_EVERYTHING "Build with most options enabled (except documentation)" OFF)
-option(ACTS_BUILD_DOC "Build documentation" OFF)
+option(ACTS_BUILD_DOCS "Build documentation" OFF)
 
 # handle option inter-dependencies and the everything flag
 # DD4hep and HepMC3 are excluded from the EVERYTHING option for now since
@@ -159,8 +159,9 @@ endif()
 if(ACTS_BUILD_EXAMPLES_PYTHIA8)
   find_package(Pythia8 REQUIRED)
 endif()
-if(ACTS_BUILD_DOC)
+if(ACTS_BUILD_DOCS)
   find_package(Doxygen 1.8.11 REQUIRED)
+  find_package(Sphinx REQUIRED)
 endif()
 
 # core library, core plugins, and other components
@@ -178,7 +179,7 @@ endif()
 add_subdirectory(Tests)
 
 # documentation
-add_subdirectory_if(doc ACTS_BUILD_DOC)
+add_subdirectory_if(docs ACTS_BUILD_DOCS)
 
 # create cmake configuration files and environment setup script
 include(ActsCreateCMakeConfig)

Examples/README.md

@@ -1,6 +1,6 @@
 # Full chain examples for development and (manual) tests
 
-**Warning** This is a set of internal tools used for the development of the
+**Warning** This is a set of internal tools used for the development of the core
 library. This is **absolutely not** intended for production use. Only the final
 build artifacts are installed; the code is not.
 

Fatras/README.md

@@ -1,16 +1,16 @@
 # FAst TRAck Simulation package
 
-This packages provides tools to run a fast track simulation on top of
-`ActsCore`. The fast track simulation (Fatras) uses the actor plug-in
-mechanism of the `Acts::Propagator` and its predictive navigation to
-simulate particle trajectories through the tracking detector.
+This packages provides tools to run a fast track simulation on top of the core
+library. The fast track simulation (Fatras) uses the actor plug-in mechanism of
+the `Acts::Propagator` and its predictive navigation to simulate particle
+trajectories through the tracking detector.
 
 As a fast track simulation, it uses the surface-based reconstruction geometry
-description, i.e. the `Acts::TrackingGeometry`, as a simulation geometry instead
-of a full detailed volumetric description. Interactions and material effects are
+description, i.e. `Acts::TrackingGeometry`, as a simulation geometry instead of
+a detailed volumetric description. Interactions and material effects are
 simulated using parametrized models:
 
-*   Multiple Coulomb scattering is simulated by Gaussian (mixture)
+-   Multiple Coulomb scattering is simulated by Gaussian (mixture)
     approximations.
-*   Ionisation loss is simulated using the Bethe-Bloch formalism.
-*   Radiation loss is simulated using the Bethe-Heitler formalism.
+-   Ionisation loss is simulated using the Bethe-Bloch formalism.
+-   Radiation loss is simulated using the Bethe-Heitler formalism.

README.md

@@ -1,63 +1,70 @@
-# A Common Tracking Software (Acts) Project
-
-[![coverage](https://badgen.net/codecov/c/github/acts-project/acts/master)](https://codecov.io/gh/acts-project/acts/branch/master) [![10.5281/zenodo.3606011](https://badgen.net/badge/DOI/10.5281%2Fzenodo.3606011/blue)](https://doi.org/10.5281/zenodo.3606011) [![Chat on Mattermost](https://badgen.net/badge/chat/on%20mattermost/cyan)](https://mattermost.web.cern.ch/acts/)
-
-1. [Introduction](#intro)
-2. [Mailing list](#mailing-list)
-6. [License and authors](#license-authors)
-
-# <a name="intro">Introduction</a>
-
-This project is an experiment-independent set of track reconstruction tools. The
-main philosophy is to provide high-level track reconstruction modules that can
-be used for any tracking detector. The description of the tracking detector's
-geometry is optimized for efficient navigation and quick extrapolation of
-tracks. Converters for several common geometry description languages exist.
-Having a fast, yet largely customizable implementation of track
-reconstruction algorithms was a primary objective for the design of this
-toolset. Additionally, the applicability to real-life HEP experiments played a
-major role in the development process. Apart from algorithmic code, this project
-also provides an event data model for the description of track parameters and
-measurements.
-
-Key features of this project include:
-
-*   Tracking geometry description which can be constructed from TGeo, DD4Hep,
-    or customized input.
-*   Simple and efficient event data model.
-*   Fast and highly flexible algorithms for track propagation and fitting.
-*   Seed finding algorithms.
-*   Fast track simulation tools based on the reconstruction geometry
-    description.
-
-The git repository for the Acts project can be found at <a href="https://gitlab.cern.ch/acts/acts-core.git">https://gitlab.cern.ch/acts/acts-core.git</a>.
-
-To get started, you can have a look at our [Getting Started Guide](getting_started.md)
-
-# <a name="mailing-list">Mailing list</a>
-
-In order to receive the latest updates, users of the Acts project are encouraged to subscribe to [acts-users@cern.ch](https://e-groups.cern.ch/e-groups/Egroup.do?egroupName=acts-users). This list provides:
-- regular updates on the software,
-- access to the Acts JIRA project for bug fixes/feature requests,
-- a common place for asking any kind of questions.
-
-If you find a bug, have a feature request, or want to contribute to Acts, please have a look at the [contribution guide](CONTRIBUTING.md).
-
-# <a name="license-authors">License and authors</a>
-
-This project is published under the terms of the Mozilla Public License, v. 2.0.
+# Acts Common Tracking Software
+
+or *A Common Tracking Software* if you do not like recursive acronyms
+
+[![10.5281/zenodo.3606011](https://badgen.net/badge/DOI/10.5281%2Fzenodo.3606011/blue)](https://doi.org/10.5281/zenodo.3606011)
+[![Chat on Mattermost](https://badgen.net/badge/chat/on%20mattermost/cyan)](https://mattermost.web.cern.ch/acts/)
+[![coverage](https://badgen.net/codecov/c/github/acts-project/acts/master)](https://codecov.io/gh/acts-project/acts/branch/master)
+
+Acts is an experiment-independent toolkit for (charged) particle track
+reconstruction in (high energy) physics experiments implemented in modern C++.
+
+More information can be found on the [Acts website](https://cern.ch/acts) and
+in the [Acts documentation](https://acts.readthedocs.io/).
+
+## Using Acts
+
+Acts is developed in C++ and is build using [CMake](https://cmake.org). Building
+the core library requires a C++17 compatible compiler,
+[Boost](http://boost.org), and [Eigen](http://eigen.tuxfamily.org). The
+following commands will clone the repository, configure, and build the core
+library
+
+```sh
+git clone https://github.com/acts-project/acts <source-dir>
+cmake -B <build-dir> -S <source-dir>
+cmake --build <build-dir>
+```
+
+For more details, e.g. specific versions and additional dependencies, have a
+look at the [getting started guide](docs/getting_started.md). If you find a bug,
+have a feature request, or want to contribute to Acts, have a look at the
+[contribution guide](CONTRIBUTING.md).
+
+## Repository organization
+
+The repository contains all code of the Acts projects, not just the core library
+that a physics experiment is expected to use as part of its reconstruction code.
+All optional components are disabled by default. Please see the
+[getting started guide](docs/getting_started.md) on how-to enable them.
+
+-   `Core/` contains the core library that provides functionality in the `Acts`
+    namespace.
+-   `Plugins/` contains plugins for core functionality that requires
+    additional external packages. The functionality also resides in the `Acts`
+    namespace.
+-   `Fatras/` provides fast track simulation tools based on the core
+    library. This is not part of the core functionality and thus resides in the
+    separate `ActsFatras` namespace.
+-   `Examples/` contains simulation and reconstruction examples. These are
+    internal tools for manual full-chain development and tests and reside in
+    the `ActsExamples` namespace.
+-   `Tests/` contains automated unit tests, integration tests, and
+    (micro-)benchmarks.
+-   `thirdparty/` contains external dependencies that are usually not available
+    through the system package manager.
+
+## Authors and license
+
+Contributors to the Acts project are listed in the [AUTHORS](AUTHORS) file.
+
+The Acts project is published under the terms of the Mozilla Public License, v. 2.0.
 A copy of the license can be found in the [LICENSE](LICENSE) file or at
 http://mozilla.org/MPL/2.0/ .
 
-Contributors to the Acts project are listed in the [AUTHORS](AUTHORS.md) file.
-
-The Acts project is based on the ATLAS tracking software. A list of contributors
-to the ATLAS tracking repository can be found at
-http://acts.web.cern.ch/ACTS/ATLAS_authors.html .
-
 The Acts project contains copies of the following external packages:
 
-*   [dfelibs](https:://gitlab.cern.ch/msmk/dfelibs) by Moritz Kiehn licensed
-    under the MIT license.
-*   [JSON for Modern C++](https://github.com/nlohmann/json) by Niels Lohmann
+-   [dfelibs](https:://gitlab.cern.ch/msmk/dfelibs) by Moritz Kiehn
+    licensed under the MIT license.
+-   [JSON for Modern C++](https://github.com/nlohmann/json) by Niels Lohmann
     licensed under the MIT License.

cmake/FindSphinx.cmake

@@ -0,0 +1,16 @@
+# Find the Sphinx documentation generator.
+#
+# This module defines the following variables:
+#   Sphinx_FOUND - whether Sphinx was found or not
+#   Sphinx_EXECUTABLE - Sphinx executable if if was found
+#
+
+find_program(
+  Sphinx_EXECUTABLE
+  NAMES sphinx-build sphinx-build-3
+  DOC "Sphinx documentation generator")
+
+include(FindPackageHandleStandardArgs)
+find_package_handle_standard_args(
+  Sphinx
+  REQUIRED_VARS Sphinx_EXECUTABLE)