restructure doxyen doc

YanzhaoW · Mar 4, 2025 · bc1389a · bc1389a
1 parent 83472bd
commit bc1389a
Show file tree

Hide file tree

Showing 18 changed files with 271 additions and 233 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,4 @@
-\mainpage
-
-# R3BRoot Software 
+# R3BRoot Software
 
 ![license](https://alfa-ci.gsi.de/shields/badge/license-GPL--3.0-orange.svg)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.5549469.svg)](https://doi.org/10.5281/zenodo.5549469) [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/9851/badge)](https://www.bestpractices.dev/projects/9851) [![fair-software.eu](https://img.shields.io/badge/fair--software.eu-%E2%97%8F%20%20%E2%97%8F%20%20%E2%97%8B%20%20%E2%97%8F%20%20%E2%97%8B-yellow)](https://fair-software.eu)
@@ -21,7 +19,7 @@ Please visit the [Doxygen documentation](https://yanzhaow.github.io/R3BRoot/) fo
 
 Detector specifics:
 
-- [NeuLAND detector](neuland/readme.md)
+- [NeuLAND detector](neuland/README.md)
 
 ## License
 

diff --git a/config/clang_tidy/README.md b/config/clang_tidy/README.md
@@ -1,4 +1,4 @@
-# Configuration for clang-tidy
+# Configuration for clang-tidy {#clang_tidy}
 
 ## Setup configuration file
 Warnings given by clang-tidy or clangd are configured in `.clang-tidy` yaml file in the nearest folder. Detector specific folders can have different configurations defined in the [global.yml](./global.yml). The customary configuration files in folders for a detector should be symbolic links to a common file located at `config/clang_tidy/${detector_name}.yml`.

diff --git a/config/dox_header.html b/config/dox_header.html
@@ -1,84 +1,91 @@
 <!-- HTML header for doxygen 1.13.2-->
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" lang="$langISO">
-    <head>
-        <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
-        <meta http-equiv="X-UA-Compatible" content="IE=11"/>
-        <meta name="generator" content="Doxygen $doxygenversion"/>
-        <meta name="viewport" content="width=device-width, initial-scale=1"/>
-        <!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
-        <!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
-        <!--BEGIN PROJECT_ICON-->
-        <link rel="icon" href="$relpath^$projecticon" type="image/x-icon" />
-        <!--END PROJECT_ICON-->
-        <link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
-        <!--BEGIN DISABLE_INDEX-->
-        <!--BEGIN FULL_SIDEBAR-->
-        <script type="text/javascript">var page_layout=1;</script>
-        <!--END FULL_SIDEBAR-->
-        <!--END DISABLE_INDEX-->
-        <script type="text/javascript" src="$relpath^jquery.js"></script>
-        <script type="text/javascript" src="$relpath^dynsections.js"></script>
-        <!--BEGIN COPY_CLIPBOARD-->
-        <script type="text/javascript" src="$relpath^clipboard.js"></script>
-        <!--END COPY_CLIPBOARD-->
-        $treeview
-        $search
-        $mathjax
-        $darkmode
-        <link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
-        $extrastylesheet
-        <script type="text/javascript" src="$relpath^doxygen-awesome-interactive-toc.js"></script>
-        <script type="text/javascript">
-            DoxygenAwesomeInteractiveToc.init()
-        </script>
-    </head>
-    <body>
-        <!--BEGIN DISABLE_INDEX-->
-        <!--BEGIN FULL_SIDEBAR-->
-        <div id="side-nav" class="ui-resizable side-nav-resizable"><!-- do not remove this div, it is closed by doxygen! -->
-            <!--END FULL_SIDEBAR-->
-            <!--END DISABLE_INDEX-->
-
-            <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
-
-                <!--BEGIN TITLEAREA-->
-                <div id="titlearea">
-                    <table cellspacing="0" cellpadding="0">
-                        <tbody>
-                            <tr id="projectrow">
-                                <!--BEGIN PROJECT_LOGO-->
-                                <td id="projectlogo"><img alt="Logo" src="$relpath^$projectlogo"$logosize/></td>
-                                <!--END PROJECT_LOGO-->
-                                <!--BEGIN PROJECT_NAME-->
-                                <td id="projectalign">
-                                    <div id="projectname">$projectname<!--BEGIN PROJECT_NUMBER--><span id="projectnumber">&#160;$projectnumber</span><!--END PROJECT_NUMBER-->
-                                    </div>
-                                    <!--BEGIN PROJECT_BRIEF--><div id="projectbrief">$projectbrief</div><!--END PROJECT_BRIEF-->
-                                </td>
-                                <!--END PROJECT_NAME-->
-                                <!--BEGIN !PROJECT_NAME-->
-                                <!--BEGIN PROJECT_BRIEF-->
-                                <td>
-                                    <div id="projectbrief">$projectbrief</div>
-                                </td>
-                                <!--END PROJECT_BRIEF-->
-                                <!--END !PROJECT_NAME-->
-                                <!--BEGIN DISABLE_INDEX-->
-                                <!--BEGIN SEARCHENGINE-->
-                                <!--BEGIN !FULL_SIDEBAR-->
-                                <td>$searchbox</td>
-                                <!--END !FULL_SIDEBAR-->
-                                <!--END SEARCHENGINE-->
-                                <!--END DISABLE_INDEX-->
-                            </tr>
-                            <!--BEGIN SEARCHENGINE-->
-                            <!--BEGIN FULL_SIDEBAR-->
-                            <tr><td colspan="2">$searchbox</td></tr>
-                            <!--END FULL_SIDEBAR-->
-                            <!--END SEARCHENGINE-->
-                        </tbody>
-                    </table>
-                </div>
-                <!--END TITLEAREA-->
-                <!-- end header part -->
+  <head>
+    <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
+    <meta http-equiv="X-UA-Compatible" content="IE=11"/>
+    <meta name="generator" content="Doxygen $doxygenversion"/>
+    <meta name="viewport" content="width=device-width, initial-scale=1"/>
+    <!--BEGIN PROJECT_NAME--><title>$projectname: $title</title><!--END PROJECT_NAME-->
+    <!--BEGIN !PROJECT_NAME--><title>$title</title><!--END !PROJECT_NAME-->
+    <!--BEGIN PROJECT_ICON-->
+    <link rel="icon" href="$relpath^$projecticon" type="image/x-icon" />
+    <!--END PROJECT_ICON-->
+    <link href="$relpath^tabs.css" rel="stylesheet" type="text/css"/>
+    <!--BEGIN DISABLE_INDEX-->
+    <!--BEGIN FULL_SIDEBAR-->
+    <script type="text/javascript">
+      var page_layout=1;
+    </script>
+    <!--END FULL_SIDEBAR-->
+    <!--END DISABLE_INDEX-->
+    <script type="text/javascript" src="$relpath^jquery.js"></script>
+    <script type="text/javascript" src="$relpath^dynsections.js"></script>
+    <!--BEGIN COPY_CLIPBOARD-->
+    <script type="text/javascript" src="$relpath^clipboard.js"></script>
+    <!--END COPY_CLIPBOARD-->
+    $treeview
+    $search
+    $mathjax
+    $darkmode
+    <link href="$relpath^$stylesheet" rel="stylesheet" type="text/css" />
+    $extrastylesheet
+    <script type="text/javascript" src="$relpath^doxygen-awesome-interactive-toc.js"></script>
+    <script type="text/javascript">
+      DoxygenAwesomeInteractiveToc.init()
+    </script>
+  </head>
+  <body>
+    <a href="https://github.com/YanzhaoW/R3BRoot" class="github-corner" aria-label="View source on GitHub"><svg width="80" height="80" viewBox="0 0 250 250" style="fill:#70B7FD; color:#fff; position: absolute; top: 0; border: 0; right: 0;" aria-hidden="true"><path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z"/><path d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2" fill="currentColor" style="transform-origin: 130px 106px;" class="octo-arm"/><path d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.7,120.9 152.7,124.9 L141.0,136.5 C139.8,137.7 141.6,141.9 141.8,141.8 Z" fill="currentColor" class="octo-body"/></svg></a><style>
+      .github-corner:hover .octo-arm{animation:octocat-wave 560ms ease-in-out}@keyframes octocat-wave{0%,100%{transform:rotate(0)}20%,60%{transform:rotate(-25deg)}40%,80%{transform:rotate(10deg)}}@media (max-width:500px){.github-corner:hover .octo-arm{animation:none}.github-corner .octo-arm{animation:octocat-wave 560ms ease-in-out}}
+    </style>
+    <!--BEGIN DISABLE_INDEX-->
+    <!--BEGIN FULL_SIDEBAR-->
+    <div id="side-nav" class="ui-resizable side-nav-resizable"><!-- do not remove this div, it is closed by doxygen! -->
+      <!--END FULL_SIDEBAR-->
+      <!--END DISABLE_INDEX-->
+      <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
+        <!--BEGIN TITLEAREA-->
+        <div id="titlearea">
+          <table cellspacing="0" cellpadding="0">
+            <tbody>
+              <tr id="projectrow">
+                <!--BEGIN PROJECT_LOGO-->
+                <td id="projectlogo"><img alt="Logo" src="$relpath^$projectlogo"$logosize/></td>
+                <!--END PROJECT_LOGO-->
+                <!--BEGIN PROJECT_NAME-->
+                <td id="projectalign">
+                  <div id="projectname">$projectname<!--BEGIN PROJECT_NUMBER--><span id="projectnumber">&#160;$projectnumber</span><!--END PROJECT_NUMBER-->
+                  </div>
+                  <!--BEGIN PROJECT_BRIEF-->
+                  <div id="projectbrief">$projectbrief</div>
+                  <!--END PROJECT_BRIEF-->
+                </td>
+                <!--END PROJECT_NAME-->
+                <!--BEGIN !PROJECT_NAME-->
+                <!--BEGIN PROJECT_BRIEF-->
+                <td>
+                  <div id="projectbrief">$projectbrief</div>
+                </td>
+                <!--END PROJECT_BRIEF-->
+                <!--END !PROJECT_NAME-->
+                <!--BEGIN DISABLE_INDEX-->
+                <!--BEGIN SEARCHENGINE-->
+                <!--BEGIN !FULL_SIDEBAR-->
+                <td>$searchbox</td>
+                <!--END !FULL_SIDEBAR-->
+                <!--END SEARCHENGINE-->
+                <!--END DISABLE_INDEX-->
+              </tr>
+              <!--BEGIN SEARCHENGINE-->
+              <!--BEGIN FULL_SIDEBAR-->
+              <tr>
+                <td colspan="2">$searchbox</td>
+              </tr>
+              <!--END FULL_SIDEBAR-->
+              <!--END SEARCHENGINE-->
+            </tbody>
+          </table>
+        </div>
+        <!--END TITLEAREA-->
+        <!-- end header part -->
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
@@ -16,6 +16,9 @@ fetchcontent_getproperties(doxygen-awesome-css SOURCE_DIR AWESOME_CSS_DIR)
 # configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
 
 # set(DOXYGEN_GENERATE_XML YES)
+
+set(DOXYGEN_PROJECT_BRIEF "R3B analysis software")
+
 set(DOXYGEN_EXTRACT_ALL YES)
 set(DOXYGEN_EXTRACT_PRIVATE NO)
 set(DOXYGEN_EXTRACT_PRIV_VIRTUAL YES)
@@ -36,7 +39,7 @@ set(DOXYGEN_IMPLICIT_DIR_DOCS NO)
 set(DOXYGEN_MAX_DOT_GRAPH_DEPTH 2)
 set(DOXYGEN_TOC_INCLUDE_HEADINGS 6)
 set(DOXYGEN_MARKDOWN_SUPPORT YES)
-# set(DOXYGEN_USE_MDFILE_AS_MAINPAGE "${PROJECT_SOURCE_DIR}/README.md")
+set(DOXYGEN_USE_MDFILE_AS_MAINPAGE "${PROJECT_SOURCE_DIR}/README.md")
 set(DOXYGEN_IMAGE_PATH "${PROJECT_SOURCE_DIR}/doc/pics" "${PROJECT_SOURCE_DIR}/neuland/docs/figs"
                        "${PROJECT_SOURCE_DIR}/neuland/shared")
 set(DOXYGEN_PYTHON_DOCSTRING NO)

diff --git a/doc/cmake_usage.md b/doc/cmake_usage.md
@@ -1,13 +1,13 @@
-## Quick look
+# Quick look {#quick_look}
 
-### Dependency graph of R3BRoot
+## Dependency graph of R3BRoot
 
 ![r3bbase](pics/r3bbase_dependers.png)
 
 > [!NOTE]
 > This dependency graph should be generated and updated by a CI pipeline.
 
-### Adding a library with a ROOT dictionary
+## Adding a library with a ROOT dictionary
 
 ```cmake
 add_library_with_dictionary(

diff --git a/doc/conan_usage.md b/doc/conan_usage.md
@@ -1,4 +1,4 @@
-# How to use Conan package manager
+# How to use Conan package manager {#conan_usage}
 
 Conan package manager is a widely-used package manager for large C++ projects. The benefits of using Conan, in the contrary to Spack, is the third-party packages are attached with the individual project, instead of an environment. Therefore, users don't need to go into a specific environment to use the packages. For more information, please refer to the [Conan Documentation](https://docs.conan.io/2/index.html).
 

diff --git a/doc/git_usage.md b/doc/git_usage.md
@@ -1,4 +1,4 @@
-## Fetch the update from an unmerged pull request (PR)
+## Fetch the update from an unmerged pull request (PR) {#git_usage}
 
 More often than not, people need to use new features from a pull request that is not yet merged to the dev branch. In this case, the new features can still be added to your local repository with following steps:
 

diff --git a/doc/utilities.md b/doc/utilities.md
@@ -0,0 +1,7 @@
+# R3BRoot Utilities {#utilities}
+
+- \subpage quick_look
+- \subpage class_interface
+- \subpage clang_tidy
+- \subpage conan_usage
+- \subpage git_usage
diff --git a/neuland/calibration/readme.md b/neuland/calibration/readme.md
@@ -1,3 +1,3 @@
-# NeuLAND calibration
+# NeuLAND Calibration {#neuland_cal}
 
 _to be added_
diff --git a/neuland/clustering/readme.md b/neuland/clustering/readme.md
@@ -0,0 +1,3 @@
+# NeuLAND Clustering algorithms {#neuland_cluster}
+
+_to be added later ..._
diff --git a/neuland/digitizing/readme.md b/neuland/digitizing/readme.md
@@ -1,4 +1,6 @@
-# Neuland Digitizing
+# NeuLAND Digitizing {#neuland_digitizing}
+
+[TOC]
 
 Digitizing is the process of converting the "raw" Monte Carlo energy depositions to experimental look-alike hits.
 

diff --git a/neuland/docs/neuland_general.md b/neuland/docs/neuland_general.md
@@ -0,0 +1,127 @@
+# NeuLAND Overview {#neuland_overview}
+
+[TOC]
+
+## General
+
+### Tasks
+
+These tasks are derived from FairTask and used in the steering macros.
+Task ending on a process usually apply a transformation to data, and take the input and output branch names as attributes, e.g.:
+
+- `R3BNeulandDigitizer`: Detector response, NeulandPoints -> NeulandHits
+- `R3BNeulandClusterFinder`: Clustering of digitized data, NeulandHits -> NeulandClusters
+
+Task ending on `mon` create control histograms, and might be quite messy. They take the input branch and output folder names as arguments. Examples:
+
+- `R3BNeulandMCMon`: Control histograms for MonteCarlo data (NeulandPoints)
+- `R3BNeulandHitMon`: Control histograms for digitized data (NeulandHits)
+- `R3BNeulandClusterMon`: ControlHistograms for clusters (NeulandClusters)
+
+
+### Data Storage
+
+Note that the classes indented for storing data (derived from TObject for usage with TClonesArray) are located in `r3bdata/neulandData`.
+
+- `R3BNeulandPoint`: Basic MonteCarlo energy depositions and light yield.
+- `R3BNeulandHit`: Combined NeulandPoints, digitized with detector response. Also indented for mapped and calibrated experimental data.
+- `R3BNeulandCluster`: Clusters consisting out of NeulandHits that belong together according to clustering conditions.
+- `R3BNeulandNeutron`: Position, Energy and Time information for neutron interactions found by event reconstruction processes
+
+
+### Configuration Storage
+
+- `R3BNeulandGeoPar`: The complete NeuLAND GeoNode used in the Simulation
+- `R3BNeulandMultiplicityCalorimetricPar`: Cuts used for the 2D Method to determine neutron multiplicities.
+
+
+### Auxiliary Classes
+
+- `R3BNeulandContFact`: Container Factory for the configuration storage classes (pure boilerplate)
+- `R3BNeulandVisualizer`: 3D display of events, prepared by the `-Mon` tasks. (Work in progress)
+- `Neuland::Neutron2DCalibr`: Calibration of cuts for the 2D neutron multiplicity method
+
+
+## Digitizing
+
+The Digitizing task `R3BNeulandDigitizer` handles the Input and Output of data while invoking the `Neuland::DigitizingEngine` for the actual processing.
+
+See [digitizing/](digitizing/readme.md) for more details.
+
+
+
+## Clustering
+
+Clustering is the process of grouping Objects together by a specified condition.
+
+The task `R3BNeulandClusterFinder` uses the  implementation in `Neuland::ClusteringEngine` of what can be called *handshake-chain clustering*, where a cluster is finished if all of the Digis in it have no neighbor that is not in the cluster.
+
+The task takes the TClonesArray NeulandHits(`R3BNeulandHit`) and fills TClonesArray NeulandClusters(`R3BNeulandCluster`).
+
+Control histograms are located  to `R3BNeulandClusterMon`.
+
+
+### Implementation of the handshake-chain clustering
+
+The implementation is a template, thus any type of object can be clustered together.
+For this example, integers are used. Starting point is an unsorted vector of integers and the clustering condition is a difference of 1 or less. For the clustering process, several iterators referencing certain points in the vector are needed:
+
+- The *begin* of the current part of the vector to look at
+- A *moving_divider* that separates the clustered part from the rest of the unclustered part
+- The fixed *end* of the vector
+- And the iterator to the object currently looked at, here called *a*
+
+```C++
+Tit moving_partition(const Tit begin, Tit moving_divider, const Tit end) const
+{
+	for (Tit a = begin; a != moving_divider; a++)
+	{
+		moving_divider = std::partition(moving_divider, end, [&](const T& b) {return f(*a, b);});
+	}
+    return moving_divider;
+}
+```
+
+In the beginning, the vector is completely unclustered and a new cluster is started with the first element:
+
+	{ 28, 13, 23, 22, 15, 16, 3, 6, 4, 26, 10, 11, 19, 8, 29, 12, 25, 30, 17, 18, 24 }
+	   │   │                                                                         │
+	   │   └ moving_divider                                                          └ end
+	   └ begin, a
+
+Now, each object from the moving_divider to the end is compared with *a*, which currently is the first element, and if the clustering condition is fulfilled, moved next to it. This is done by std::partition. Now the *moving_divider* is set to the end of this partitioned part, and the next element between the current *a* and the *moving_divider* becomes the new *a*, which the unclustered part is compared to:
+
+	{ 28, 29, 30, 22, 15, 16, 3, 6, 4, 26, 10, 11, 19, 8, 23, 12, 25, 13, 17, 18, 24 }
+	   │   │       │                                                                 │
+	   │   a       └ moving_divider                                                  └ end
+	   └ begin
+
+This continues until the *moving_divider* is reached, at this point the cluster is finished and extracted, and a new cluster is started:
+
+	{ xx, xx, xx, 22, 15, 16, 3, 6, 4, 26, 10, 11, 19, 8, 23, 12, 25, 13, 17, 18, 24 }
+	               │   │                                                             │
+	               │   └ moving_divider                                              └ end
+	               └ begin, a
+
+Note that the *moving_divider* does move every time std::partition adds new objects to the cluster, thus also these times are iterated over:
+
+
+	{ xx, xx, xx, 22, 23, 16, 3, 6, 4, 26, 10, 11, 19, 8, 15, 12, 25, 13, 17, 18, 24 }
+	               │   │   │                                                         │
+	               │   a   └ moving_divider                                          └ end
+	               └ begin
+	{ xx, xx, xx, 22, 23, 24, 3, 6, 4, 26, 10, 11, 19, 8, 15, 12, 25, 13, 17, 18, 16 }
+	               │       │  │                                                      │
+	               │       a  └ moving_divider                                       └ end
+	               └ begin
+	{ xx, xx, xx, 22, 23, 24, 25, 6, 4, 26, 10, 11, 19, 8, 15, 12, 3, 13, 17, 18, 16 }
+	               │           │  │                                                  │
+	               │           a  └ moving_divider                                   └ end
+	               └ begin
+
+Note that for this process, the order of the objects is irrelevant. The algorithm will always find all elements that belong together.
+
+In this example, the result is:
+
+	{ 28, 29, 30 }, { 22, 23, 24, 25, 26 }, { 4, 3 }, { 10, 11, 12, 13 }, { 8 }, { 19, 18, 17, 16, 15 }, { 6 }
+
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# NeuLAND Clustering algorithms {#neuland_cluster}

		_to be added later ..._