Update Doxygen format (O2-525) (#1813)

ihrivnac · dberzano · commit 268e5f2d1d6d · 2019-04-16T16:59:07.000+02:00
* Introduce structuring of doc pages
* Add special comments to make Markdown and Doxygen coexist
diff --git a/Algorithm/README.md b/Algorithm/README.md
@@ -0,0 +1,3 @@
+\page refAlgorithm Module 'Algorithm'
+
+A description of this module is not yet available.
diff --git a/CCDB/README.md b/CCDB/README.md
@@ -1,3 +1,5 @@
+\page refCCDB Module 'CCDB'
+
 ## CCDB API
 
 The CCDB API class (`CcdbApi`) is implemented using libcurl and gives
diff --git a/Common/README.md b/Common/README.md
@@ -0,0 +1,12 @@
+\page refCommon Module 'Common'
+
+This module contains the following submodules:
+
+- \subpage refCommonConstants
+- \subpage refCommonField
+- \subpage refCommonMathUtils
+- \subpage refCommonSimConfig
+- \subpage refCommonTopologies
+- \subpage refCommonTypes
+- \subpage refCommonUtils
+- \subpage refCommonmaps
diff --git a/Common/SimConfig/doc/ConfigurableParam.md b/Common/SimConfig/doc/ConfigurableParam.md
@@ -1,3 +1,5 @@
+\page refCommonSimConfig SimConfig
+
 # Configurable Parameters
 
 This is a short README for configurable parameters as offered by 
diff --git a/DataFormats/README.md b/DataFormats/README.md
@@ -0,0 +1,13 @@
+\page refDataFormats Module 'DataFormats'
+
+This module contains the following submodules:
+
+- \subpage refDataFormatsDetectors
+- \subpage refDataFormatsHeaders
+- \subpage refDataFormatsLegacy
+- \subpage refDataFormatsMemoryResources
+- \subpage refDataFormatsParameters
+- \subpage refDataFormatsReconstruction
+- \subpage refDataFormatsTimeFrame
+- \subpage refDataFormatscommon
+- \subpage refDataFormatssimulation
diff --git a/Detectors/ITSMFT/MFT/README.md b/Detectors/ITSMFT/MFT/README.md
@@ -1,3 +1,5 @@
+\page refMFT MFT
+
 The Muon Forward Tracker
 ========================
 
@@ -7,4 +9,3 @@ The Muon Forward Tracker
 #### What? 
 * A Si-tracking detector designed to add vertexing capabilities to the MUON spectrometer.
 
-
diff --git a/Detectors/ITSMFT/MFT/base/README.md b/Detectors/ITSMFT/MFT/base/README.md
@@ -1,3 +1,5 @@
+\page refMFTbase MFT base
+
 # MFT base classes 
 
 Constants: static constants for the MFT
diff --git a/Detectors/ITSMFT/MFT/reconstruction/README.md b/Detectors/ITSMFT/MFT/reconstruction/README.md
@@ -1,3 +1,5 @@
+\page refMFTreconstruction MFT reconstruction
+
 MFT track reconstruction
 ========================
 
diff --git a/Detectors/ITSMFT/README.md b/Detectors/ITSMFT/README.md
@@ -0,0 +1,7 @@
+\page refDetectorsITSMFT ITSMFT
+
+This is a top page for the ITSMFT detector documentation.
+
+- \subpage refMFT
+- \subpage refMFTbase
+- \subpage refMFTreconstruction
diff --git a/Detectors/MUON/MCH/Contour/README.md b/Detectors/MUON/MCH/Contour/README.md
@@ -1,3 +1,5 @@
+\page refMUONMCHContour MCH Contour
+
 # MCH Contour library
 
 A header-only library to work with contours (polygons).
diff --git a/Detectors/MUON/MCH/Mapping/Impl3/README.md b/Detectors/MUON/MCH/Mapping/Impl3/README.md
@@ -1,3 +1,5 @@
+\page refMUONMCHMappingImpl3 MCH Mapping Impl3
+
 # MCH Mapping Implementation
 
 This is an implementation of the [C interface](../Interface/include/MCHMappingInterface/SegmentationCInterface.h) of the MCH mapping.
diff --git a/Detectors/MUON/MCH/Mapping/README.md b/Detectors/MUON/MCH/Mapping/README.md
@@ -1,3 +1,5 @@
+\page refMUONMCHMapping MCH Mapping
+
 # MCH Mapping
 
 # API
diff --git a/Detectors/MUON/MCH/Mapping/SegContour/README.md b/Detectors/MUON/MCH/Mapping/SegContour/README.md
@@ -1,3 +1,5 @@
+\page refMUONMCHMappingSegContour MCH Mapping SegContour
+
 # Segmentation contours
 
 This module contains convenience functions that can compute the
diff --git a/Detectors/MUON/MCH/Mapping/test/src/README.md b/Detectors/MUON/MCH/Mapping/test/src/README.md
@@ -1,3 +1,5 @@
+\page refMUONMCHMappingtest  MCH Mapping test
+
 By default the tests are running without any input.
 
 If you want to go further though, you can input a JSON file containing test positions using the  `--testpos` option (it is an option of the test module, not of the test program itself, hence the `--` syntax) and call (part of) the test like so :  
diff --git a/Detectors/MUON/MID/Clustering/README.md b/Detectors/MUON/MID/Clustering/README.md
@@ -1,3 +1,5 @@
+\page refMUONMIDClustering MID Clustering
+
 # Running MID clustering
 
 The MID clustering takes as input the "digits" and returns the resulting clusters.
diff --git a/Detectors/MUON/MID/Tracking/README.md b/Detectors/MUON/MID/Tracking/README.md
@@ -1,3 +1,5 @@
+\page refMUONMIDTracking MID Tracking
+
 # Running MID Tracking
 
 The MID tracking takes as input the clusters and returns a vector of reconstructed tracks.
diff --git a/Detectors/MUON/README.md b/Detectors/MUON/README.md
@@ -0,0 +1,11 @@
+\page refDetectorsMUON MUON
+
+This is a top page for the MUON detector documentation.
+
+- \subpage refMUONMIDClustering
+- \subpage refMUONMIDTracking
+- \subpage refMUONMCHMappingSegContour
+- \subpage refMUONMCHMapping
+- \subpage refMUONMCHMappingtest
+- \subpage refMUONMCHMappingImpl3
+- \subpage refMUONMCHContour
diff --git a/Detectors/README.md b/Detectors/README.md
@@ -0,0 +1,18 @@
+\page refDetectors Module 'Detectors'
+
+This module contains the following submodules:
+
+- \subpage refDetectorsBase
+- \subpage refDetectorsEMCAL
+- \subpage refDetectorsFIT
+- \subpage refDetectorsGeometry
+- \subpage refDetectorsGlobalTracking
+- \subpage refDetectorsHMPID
+- \subpage refDetectorsITSMFT
+- \subpage refDetectorsMUON
+- \subpage refDetectorsPHOS
+- \subpage refDetectorsPassive
+- \subpage refDetectorsTOF
+- \subpage refDetectorsTPC
+- \subpage refDetectorsTRD
+- \subpage refDetectorsZDC
diff --git a/Detectors/TPC/README.md b/Detectors/TPC/README.md
@@ -0,0 +1,5 @@
+\page refDetectorsTPC TPC
+
+This is a top page for the TPC detector documentation.
+
+- \subpage refTPCworkflow
diff --git a/Detectors/TPC/workflow/README.md b/Detectors/TPC/workflow/README.md
@@ -1,3 +1,5 @@
+\page refTPCworkflow TPC workflow
+
 # DPL workflows for the TPC
 
 ## TPC reconstruction workflow
diff --git a/Detectors/TRD/README.md b/Detectors/TRD/README.md
@@ -0,0 +1,5 @@
+\page refDetectorsTRD TRD
+
+This is a top page for the TRD detector documentation.
+
+- \subpage refTRDbase
diff --git a/Detectors/TRD/base/README.md b/Detectors/TRD/base/README.md
@@ -1,3 +1,5 @@
+\page refTRDbase TRD base
+
 This is a short documention for the TRD base software for O2
 
 At the moment this is just a poc for doing documentation.
diff --git a/EventVisualisation/Base/README.md b/EventVisualisation/Base/README.md
@@ -1,3 +1,5 @@
+\page refEventVisualisationBase EventVisualisation Base
+
 Example 1
 =========
 
diff --git a/EventVisualisation/README.md b/EventVisualisation/README.md
@@ -0,0 +1,6 @@
+\page refEventVisualisation Module 'EventVisualisation'
+
+This module contains the following submodules:
+
+- \subpage refEventVisualisationBase
+
diff --git a/Examples/ExampleModule1/README.md b/Examples/ExampleModule1/README.md
@@ -1,3 +1,5 @@
+\page refExamplesExampleModule1 Example Module 1
+
 Example 1
 =========
 
diff --git a/Examples/ExampleModule2/README.md b/Examples/ExampleModule2/README.md
@@ -1,3 +1,5 @@
+\page refExamplesExampleModule2 Example Module 2
+
 Example 2
 =========
 
diff --git a/Examples/README.md b/Examples/README.md
@@ -0,0 +1,8 @@
+\page refExamples Module 'Examples'
+
+This module contains the following submodules:
+
+- \subpage refExamplesflp2epn
+- \subpage refExamplesflp2epn-distributed
+- \subpage refExamplesExampleModule1
+- \subpage refExamplesExampleModule2
diff --git a/Examples/flp2epn-distributed/README.md b/Examples/flp2epn-distributed/README.md
@@ -1,3 +1,5 @@
+\page refExamplesflp2epn-distributed Example flp2epn-distributed
+
 #### Prototype Devices for the transport between FLPs and EPNs
 --------------------------------------------------------------
 
diff --git a/Examples/flp2epn/README.md b/Examples/flp2epn/README.md
@@ -1,3 +1,5 @@
+\page refExamplesflp2epn Example flp2epn
+
 #### Example devices - testFLP and testEPN
 --------------------------------------------------------------
 
diff --git a/Framework/Core/COOKBOOK.md b/Framework/Core/COOKBOOK.md
@@ -1,3 +1,5 @@
+\page refFrameworkCoreCOOKBOOK Core COOKBOOK
+
 # Data Processing Layer Cookbook
 
 This is a work in progress entrypoint for common DPL related tasks.
diff --git a/Framework/Core/README.md b/Framework/Core/README.md
@@ -1,3 +1,6 @@
+\page refFrameworkCore Core
+\subpage refFrameworkCoreCOOKBOOK Core COOKBOOK
+
 # Data Processing Layer in O2 Framework
 
 ## Status quo and motivation for an O2 Data Processing Layer
diff --git a/Framework/Foundation/README.md b/Framework/Foundation/README.md
@@ -1,3 +1,5 @@
+\page refFrameworkFoundation Foundation
+
 ## O2 Framework Foundation
 
 Nothing but pure C++ helpers go here. No dependencies allowed.
diff --git a/Framework/README.md b/Framework/README.md
@@ -0,0 +1,10 @@
+\page refFramework Module 'Framework'
+
+This module contains the following submodules:
+
+- \subpage refFrameworkArrowTests
+- \subpage refFrameworkCore
+- \subpage refFrameworkDebugGUI
+- \subpage refFrameworkFoundation
+- \subpage refFrameworkTestWorkflows
+- \subpage refFrameworkUtils
diff --git a/Generators/README.md b/Generators/README.md
@@ -0,0 +1,3 @@
+\page refGenerators Module 'Generators'
+
+A description of this module is not yet available.
diff --git a/README.md b/README.md
@@ -1,7 +1,8 @@
 
-ALICE O2 software
-=================
+ALICE O2 software    {#mainpage}
+===================
 
+<!--  \cond EXCLUDE_FOR_DOXYGEN -->
 [![codecov](https://codecov.io/gh/AliceO2Group/AliceO2/branch/dev/graph/badge.svg)](https://codecov.io/gh/AliceO2Group/AliceO2/branches/dev)
 [![JIRA](https://img.shields.io/badge/JIRA-Report%20issue-blue.svg)](https://alice.its.cern.ch/jira/secure/CreateIssue.jspa?pid=11201&issuetype=1)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.1493334.svg)](https://doi.org/10.5281/zenodo.1493334)
@@ -10,6 +11,7 @@ ALICE O2 software
 [![](http://ali-ci.cern.ch/repo/buildstatus/AliceO2Group/AliceO2/dev/build_o2_macos.svg)](https://ali-ci.cern.ch/repo/logs/AliceO2Group/AliceO2/dev/latest/build_o2_macos/fullLog.txt)
 [![](http://ali-ci.cern.ch/repo/buildstatus/AliceO2Group/AliceO2/dev/build_o2checkcode_o2.svg)](https://ali-ci.cern.ch/repo/logs/AliceO2Group/AliceO2/dev/latest/build_o2checkcode_o2/fullLog.txt)
 [![](http://ali-ci.cern.ch/repo/buildstatus/AliceO2Group/AliceO2/dev/build_O2_o2-dev-fairroot.svg)](https://ali-ci.cern.ch/repo/logs/AliceO2Group/AliceO2/dev/latest/build_O2_o2-dev-fairroot/fullLog.txt)
+<!--  \endcond  -->
 
 ### Scope
 The ALICE O2 software repository contains the framework, as well as the detector specific, code for the reconstruction, calibration and simulation for the ALICE experiment at CERN for Run 3 and 4. It also encompasses the commonalities such as the data format, and the global algorithms like the global tracking.
@@ -38,12 +40,12 @@ To access the resulting documentation, open doc/html/index.html in your
 build directory. To install the documentation when calling `make install`
 turn on the variable `DOC_INSTALL`.
 
-Doxygen documentation is also available online [here](http://aliceo2group.github.io/AliceO2/)
+The instruction how to add the documentation pages (README.md) are available [here](doc/DoxygenInstructions.md).
 
 ### Build system (cmake) and directory structure
 The code organisation is described [here](doc/CodeOrganization.md).
 The build system (cmake) is described [here](doc/CMakeInstructions.md).
 
 ### Formatting
 Rules and instructions are available in the repository
-[CodingGuidelines](https://github.com/AliceO2Group/CodingGuidelines). 
+[CodingGuidelines](https://github.com/AliceO2Group/CodingGuidelines).
diff --git a/Steer/DigitizerWorkflow/README.md b/Steer/DigitizerWorkflow/README.md
@@ -1,3 +1,5 @@
+\page refSteerDigitizerWorkflow Digitizer Workflow
+
 This is a short documention for the DPL-DigitizerWorkflow example
 
 # Status/Description of implementation
diff --git a/Steer/README.md b/Steer/README.md
@@ -1,3 +1,5 @@
+\page refSteer Module 'Steer'
+
 # ALICEO2 Steer
 
 This directory contains ALICE O2 specific customizations
@@ -8,3 +10,7 @@ a) quick prototyping of ideas without having to require immediate changes in Fai
    but with the idea to give back the changes some day
 b) adaptations to classes because some things are done differently than in FairRoot
    (MC truth handling, parameter handling etc)
+
+This module contains the following submodules:
+
+\subpage refSteerDigitizerWorkflow
diff --git a/Testing/README.md b/Testing/README.md
@@ -0,0 +1,3 @@
+\page refTesting Module 'Testing'
+
+A description of this module is not yet available.
diff --git a/Utilities/MCStepLogger/README.md b/Utilities/MCStepLogger/README.md
@@ -1,3 +1,5 @@
+\page refUtilitiesMCStepLogger MCStepLogger
+
 ### NOTE: The MCStepLogger has moved to https://github.com/AliceO2Group/VMCStepLogger.git
 
 ## MCStepLogger
diff --git a/Utilities/O2Device/README.md b/Utilities/O2Device/README.md
@@ -1,3 +1,5 @@
+\page refUtilitiesO2Device O2Device
+
 # O2Device
 
 The O2Device is meant to build O2 specific behaviours on top of plain FairMQDevices.
diff --git a/Utilities/PCG/README.md b/Utilities/PCG/README.md
@@ -1,3 +1,5 @@
+\page refUtilitiesPCG PCG
+
 # PCG Random Number Generation, C++ Edition
 
 [PCG-Random website]: http://www.pcg-random.org
diff --git a/Utilities/README.md b/Utilities/README.md
@@ -0,0 +1,23 @@
+<!-- doxy
+\page refUtilities Module 'Utilities'
+/doxy -->
+
+Module 'Utilities'
+===================
+
+There is no module description yet.
+
+<!-- doxy
+This module contains the following submodules:
+
+- \subpage refUtilitiesDataCompression
+- \subpage refUtilitiesDataFlow
+- \subpage refUtilitiesMCStepLogger
+- \subpage refUtilitiesO2Device
+- \subpage refUtilitiesO2MessageMonitor
+- \subpage refUtilitiesPCG
+- \subpage refUtilitiesPublishers
+- \subpage refUtilitiesTools
+- \subpage refUtilitiesaliceHLTwrapper
+- \subpage refUtilitieshough
+/doxy -->
diff --git a/Utilities/Tools/README.md b/Utilities/Tools/README.md
@@ -1,3 +1,5 @@
+\page refUtilitiesTools Tools
+
 # Using the Code checker / fixer
 
 You can run the code checker and have it fix the errors it reports
diff --git a/Utilities/hough/README.md b/Utilities/hough/README.md
@@ -1,3 +1,5 @@
+\page refUtilitieshough Hough Transform
+
 Hough Transform
 ===============
 
diff --git a/doc/CLion.md b/doc/CLion.md
@@ -1,3 +1,5 @@
+\page refdocCLion CLion
+
 Here are a number of instructions and tips on how to use at best the IDE called [CLion from Jetbrains](https://www.jetbrains.com/clion/).
 
 ## Installation
diff --git a/doc/CMakeInstructions.md b/doc/CMakeInstructions.md
@@ -1,3 +1,5 @@
+\page refdocCMakeInstructions CMake Instructions
+
 CMake
 =====
 
diff --git a/doc/CodeOrganization.md b/doc/CodeOrganization.md
@@ -1,3 +1,5 @@
+\page refdocCodeOrganization Code Organization
+
 Code organisation
 =================
 
diff --git a/doc/DetectorSimulation.md b/doc/DetectorSimulation.md
@@ -1,3 +1,5 @@
+\page refdocDetectorSimulation Detector Simulation
+
 # Detector simulation documentation
 
 The present document collects information about the ALICE detector simulation executable and digitization procedure used in LHC Run3.
diff --git a/doc/DoxygenInstruction.md b/doc/DoxygenInstruction.md
diff --git a/doc/ManPages.md b/doc/ManPages.md
diff --git a/doc/README.md b/doc/README.md
diff --git a/doc/doxyfile.in b/doc/doxyfile.in
diff --git a/doc/scripts/filter_for_doxygen.sh b/doc/scripts/filter_for_doxygen.sh
