From 439d2ad2faa7424722e34951419e436cc9254cdd Mon Sep 17 00:00:00 2001
From: Andrii Verbytskyi <andrii.verbytskyi@cern.ch>
Date: Fri, 24 May 2024 15:12:43 +0200
Subject: [PATCH] Move the documentation from packagedoc headers to README.md
for Generators
Move the documentation from packagedoc headers to README.md for Generators
---
Generators/CosmicGenerator/README.md | 33 +++++++++++++
Generators/CosmicGenerator/doc/packagedoc.h | 47 -------------------
Generators/GeneratorFilters/doc/packagedoc.h | 35 --------------
.../{doc/packagedoc.h => README.md} | 17 ++-----
.../{doc/packagedoc.h => README.md} | 18 ++-----
.../Herwig7_i/{doc/packagedoc.h => README.md} | 22 ++-------
.../Hijing_i/{doc/packagedoc.h => README.md} | 14 +-----
7 files changed, 48 insertions(+), 138 deletions(-)
create mode 100644 Generators/CosmicGenerator/README.md
delete mode 100644 Generators/CosmicGenerator/doc/packagedoc.h
delete mode 100644 Generators/GeneratorFilters/doc/packagedoc.h
rename Generators/GeneratorObjectsAthenaPool/{doc/packagedoc.h => README.md} (67%)
rename Generators/GeneratorObjectsTPCnv/{doc/packagedoc.h => README.md} (76%)
rename Generators/Herwig7_i/{doc/packagedoc.h => README.md} (76%)
rename Generators/Hijing_i/{doc/packagedoc.h => README.md} (63%)
diff --git a/Generators/CosmicGenerator/README.md b/Generators/CosmicGenerator/README.md
new file mode 100644
index 000000000000..3791e33b7d1d
--- /dev/null
+++ b/Generators/CosmicGenerator/README.md
@@ -0,0 +1,33 @@
+# CosmicGenerator
+
+Authors: W. Seligman, M. Shapiro, I. Hinchliffe, M. Zdrazil,
+
+## General information
+
+CosmicGenerator package is a generator used for the cosmic particle production.
+The output will is stored in the transient event store so it can be passed to t
+he simulation.
+
+The CosmicGenerator is used e.g. by default by the G4 cosmic simulation as a so
+urce of cosmic muons at ground level.
+
+One of the features of the CosmicGenerator is the ability to filter primary muo
+ns depending on their direction and energy.
+If you look in jobOptions_ConfigCosmicProd.py, you will find that the following
+ properties can be set:
+
+ - CosmicGenerator.emin, CosmicGenerator.emax: energy range for the primary muon
+
+ - CosmicGenerator.xvert_low, CosmicGenerator.xvert_high, CosmicGenerator.zvert_low, CosmicGenerator.zvert_high: the (x,z) surface at ground level in which the primary vertex has to be created
+
+ - CosmicGenerator.yvert_val: the y quota at which the primary vertexes must be created (i.e. the "ground level")
+
+ - CosmicGenerator.ctcut: angular cut (wrt to the vertical)
+
+Another set of properties allows further optimization:
+
+ - CosmicGenerator.OptimizeForCavern: if True, muons are passed to the simulation only if they are pointing towards the interaction point, within a given tolerance. In order for this to work, the CosmicGenerator must be informed on where the IP is exactly. This is what the next properties are for
+
+ - CosmicGenerator.IPx, CosmicGenerator.IPy, CosmicGenerator.IPz: the (x,y,z) coordinates of the IP
+
+ - CosmicGenerator.Radius: the tolerance of the direction filtering. Only muons pointing inside a sphere centered in the IP with the given radius will be accepted.
diff --git a/Generators/CosmicGenerator/doc/packagedoc.h b/Generators/CosmicGenerator/doc/packagedoc.h
deleted file mode 100644
index 82eed8384893..000000000000
--- a/Generators/CosmicGenerator/doc/packagedoc.h
+++ /dev/null
@@ -1,47 +0,0 @@
-/*
- Copyright (C) 2002-2017 CERN for the benefit of the ATLAS collaboration
-*/
-
-/**
-@page CosmicGenerator_page CosmicGenerator
-@author W. Seligman, M. Shapiro, I. Hinchliffe, M. Zdrazil,
-
-@section CosmicGenerator_General information
-
-CosmicGenerator package is a generator used for the cosmic particle production.
-The output will is stored in the transient event store so it can be passed to t
-he simulation.
-
-The CosmicGenerator is used e.g. by default by the G4 cosmic simulation as a so
-urce of cosmic muons at ground level.
-
-One of the features of the CosmicGenerator is the ability to filter primary muo
-ns depending on their direction and energy.
-If you look in jobOptions_ConfigCosmicProd.py, you will find that the following
- properties can be set:
-
- * CosmicGenerator.emin, CosmicGenerator.emax: energy range for the primary m
-uon
- * CosmicGenerator.xvert_low, CosmicGenerator.xvert_high, CosmicGenerator.zv
-ert_low, CosmicGenerator.zvert_high: the (x,z) surface at ground level in which
- the primary vertex has to be created
- * CosmicGenerator.yvert_val: the y quota at which the primary vertexes must
- be created (i.e. the "ground level")
- * CosmicGenerator.ctcut: angular cut (wrt to the vertical)
-
-Another set of properties allows further optimization:
-
- * CosmicGenerator.OptimizeForCavern: if True, muons are passed to the simul
-ation only if they are pointing towards the interaction point, within a given t
-olerance. In order for this to work, the CosmicGenerator must be informed on wh
-ere the IP is exactly. This is what the next properties are for
- * CosmicGenerator.IPx, CosmicGenerator.IPy, CosmicGenerator.IPz: the (x,y,z
-) coordinates of the IP
- * CosmicGenerator.Radius: the tolerance of the direction filtering. Only mu
-ons pointing inside a sphere centered in the IP with the given radius will be a
-ccepted.
-
-
-
-
-*/
diff --git a/Generators/GeneratorFilters/doc/packagedoc.h b/Generators/GeneratorFilters/doc/packagedoc.h
deleted file mode 100644
index f5e7e0632813..000000000000
--- a/Generators/GeneratorFilters/doc/packagedoc.h
+++ /dev/null
@@ -1,35 +0,0 @@
-/*
- Copyright (C) 2002-2017 CERN for the benefit of the ATLAS collaboration
-*/
-
-/**
-
- <i>
-
-This package contains a set of algorithms that run from within Athena.
-The algorithms extract the generated Monte Carlo event from the
-transient event store (Storegate) and then test for various criteria.
-The base class GenFilter extracts the event from Storegate
-and makes it available; all the other filter classes inherit from this.
-
-The events are in HepMC format which is independent of the actual
-Monte Carlo generator. The same filter can therefore be used with
-Isajet, Herwig, Pythia etc. Users are directed to the
-ElectronFilter which illustrates the basic logic and can be used
-as a template for preparing other classes. (Note that SampleFilter
-is easier to read as it does not use the base class, but users
-should not use SampleFilter as a template as their code will not then
-be protected against changes in the way the events are held in
-Storegate).
-
-@author Ian Hinchliffe, Judith Katzy
-
-</i>
-
-@page GeneratorFilters_page
-
-
-
-
-
-*/
diff --git a/Generators/GeneratorObjectsAthenaPool/doc/packagedoc.h b/Generators/GeneratorObjectsAthenaPool/README.md
similarity index 67%
rename from Generators/GeneratorObjectsAthenaPool/doc/packagedoc.h
rename to Generators/GeneratorObjectsAthenaPool/README.md
index 02448b401a65..55ebc677c4e0 100644
--- a/Generators/GeneratorObjectsAthenaPool/doc/packagedoc.h
+++ b/Generators/GeneratorObjectsAthenaPool/README.md
@@ -1,24 +1,15 @@
-/*
- Copyright (C) 2002-2017 CERN for the benefit of the ATLAS collaboration
-*/
-
-/**
-@page GeneratorObjectsAthenaPool_page GeneratorObjectsAthenaPool Package
+# GeneratorObjectsAthenaPool Package
The package which defines POOL converters for general Monte-Carlo classes.
-@authors Sebastien Binet, Georgios Stavropoulos, Davide Costanzo
+Authors: Sebastien Binet, Georgios Stavropoulos, Davide Costanzo
-@section GeneratorObjectsAthenaPool_GeneratorObjectsAthenaPoolIntro Introduction
+## Introduction
The MonteCarlo classes (e.g. @c HepMC::GenEvent ) are stored on disk through the so-called POOL persistification technology which insulates client code (Athena) from technology details and provides transparent switch of different storage backends (ROOT, MySQL,...)
This package provides the needed boilerplate code to use the T/P converters provided by the GeneratorObjectsTPCnv package (see twiki page about Transient/Persistent separation: https://twiki.cern.ch/twiki/bin/view/Atlas/TransientPersistentSeparation) and make them available to the GAUDI framework.
-@section GeneratorObjectsAthenaPool_GeneratorObjectsAthenaPoolSeeAlso See also
+## See also
You may also be interested in having a look at the GeneratorObjectsTPCnv package which defines and provides various T/P converters for the MonteCarlo classes.
-
-
-
-*/
diff --git a/Generators/GeneratorObjectsTPCnv/doc/packagedoc.h b/Generators/GeneratorObjectsTPCnv/README.md
similarity index 76%
rename from Generators/GeneratorObjectsTPCnv/doc/packagedoc.h
rename to Generators/GeneratorObjectsTPCnv/README.md
index a789abdb29f7..5c47530127ec 100644
--- a/Generators/GeneratorObjectsTPCnv/doc/packagedoc.h
+++ b/Generators/GeneratorObjectsTPCnv/README.md
@@ -1,26 +1,16 @@
-/*
- Copyright (C) 2002-2017 CERN for the benefit of the ATLAS collaboration
-*/
-
-/**
-
-@page GeneratorObjectsTPCnv_page GeneratorObjectsTPCnv Package
+# GeneratorObjectsTPCnv Package
This package defines the so-called T/P converters for Monte-Carlo classes.
-@authors Sebastien Binet, Georgios Stavropoulos, Davide Costanzo
+Authors Sebastien Binet, Georgios Stavropoulos, Davide Costanzo
-@section GeneratorObjectsTPCnv_GeneratorObjectsTPCnvIntro Introduction
+## Introduction
The ATLAS software, in order to provide backward compatibility (and extensive schema evolution) of on-disk stored data, decouples the transient classes that one manipulates in-memory and the persistent classes that one writes on disk.
To achieve this, a robust (and quite performant) Transient/Persistent separation library has been written.
This library has the responsibility for converting all (or a subset of) previous versions of persistent classes into the latest and finest in-memory representation of a given class.
-The GeneratorObjectsTPCnv package provides that functionality for the MonteCarlo objects (e.g. @c HepMC::GenEvent).
+The GeneratorObjectsTPCnv package provides that functionality for the MonteCarlo objects (e.g. `HepMC::GenEvent`).
As other transient (and hence persistent) classes may also need to re-use that functionality, the core of the conversion is provided as an installed library (so symbols are exported) so other component and/or installed libraries can link against (to prevent code duplication).
See https://twiki.cern.ch/twiki/bin/view/Atlas/TransientPersistentSeparation for a broader and more detailed of how the T/P separation of classes is working and implemented.
-
-
-
-*/
diff --git a/Generators/Herwig7_i/doc/packagedoc.h b/Generators/Herwig7_i/README.md
similarity index 76%
rename from Generators/Herwig7_i/doc/packagedoc.h
rename to Generators/Herwig7_i/README.md
index f84b4473735b..c263d5ef07a6 100644
--- a/Generators/Herwig7_i/doc/packagedoc.h
+++ b/Generators/Herwig7_i/README.md
@@ -1,11 +1,6 @@
-/*
- Copyright (C) 2002-2017 CERN for the benefit of the ATLAS collaboration
-*/
+# Herwig7_i
-/**
-@page Herwig7_i_page Herwig7_i
-
-@section Herwig7_i_Herwig7ForATLAS Herwig 7 for ATLAS
+## Herwig 7 for ATLAS
Herwig 7 is a general-purpose event generator written in C++.
It provides a significant amount of improvements and new features with respect
@@ -21,7 +16,7 @@ For more information on Herwig 7 in ATLAS please refer to the TWiki pages at
https://twiki.cern.ch/twiki/bin/view/AtlasProtected/Herwig7ForAtlas
-@subsection AthenaInterface The Interface between Herwig7 and Athena
+## The Interface between Herwig7 and Athena
Herwig 7 can be used in the same way as the Herwig++ 2.X series, in particular
it is capable of showering MadGraph5_aMC\@NLO and PowhegBox events.
@@ -33,15 +28,8 @@ matching strategies, called 'subtractive' (MCatNLO-like) and 'multiplicative'
shower and the dipole shower. Integration of these new features in the interface
is still ongoing and will need to be validated afterwards.
-\note Currently, showering of Alpgen inputs is deprecated and was removed from
+### Note
+ Currently, showering of Alpgen inputs is deprecated and was removed from
the interface since it would require a significant amount of validation. In case
your are interested in this, please let us know.
-
-@subsection TableOfContents Contents of this Documentation
-
-- @ref Links
-- @ref FAQ
-- @ref MC15JobOptions
-
-*/
diff --git a/Generators/Hijing_i/doc/packagedoc.h b/Generators/Hijing_i/README.md
similarity index 63%
rename from Generators/Hijing_i/doc/packagedoc.h
rename to Generators/Hijing_i/README.md
index 2277533fc2e1..c10a9dd4e2a1 100644
--- a/Generators/Hijing_i/doc/packagedoc.h
+++ b/Generators/Hijing_i/README.md
@@ -1,19 +1,9 @@
-/*
- Copyright (C) 2002-2017 CERN for the benefit of the ATLAS collaboration
-*/
+# Hijing
-/**
-@page Hijing_i_page
-
-@author Georgios Stavropoulos (George.Stavropoulos@cern.ch)
+Author: Georgios Stavropoulos (George.Stavropoulos@cern.ch)
Documentation for the Hijing MC can be found here:
http://www-nsdth.lbl.gov/~xnwang/hijing/index.html
The Hijing interface documentation and explanations how to use Hijing in Athena framework is described here:
https://svnweb.cern.ch/trac/atlasoff/browser/Generators/Hijing_i/trunk/doc/Hijing.pdf
-
-
-
-
-*/
--
GitLab