Update documentation based on various feedback (QC-313) (#370)

Barthelemy · web-flow · commit c5ac16747f18 · 2020-04-16T10:53:49.000+02:00
* Following feedback from HMPID

* changing the name of task in 2 places

* load readout environment

* proper url to files

* fix path QC-313

* addresses Piotr's comments
diff --git a/doc/ModulesDevelopment.md b/doc/ModulesDevelopment.md
@@ -41,7 +41,7 @@ The main data flow is represented in blue. Data samples are selected by the Data
 
 [Data Processing Layer](https://github.com/AliceO2Group/AliceO2/blob/dev/Framework/Core/README.md) is a software framework developed as a part of O2 project. It structurizes the computing into units called _Data Processors_ - processes that communicate with each other via messages. DPL takes care of generating and running the processing topology out of user declaration code, serializing and deserializing messages, providing the data processors with all the anticipated messages for a given timestamp and much more. Each piece of data is characterized by its `DataHeader`, which consists (among others) of `dataOrigin`, `dataDescription` and `SubSpecification` - for example `{"MFT", "TRACKS", 0}`.
 
-An example of a workflow definition which describes the processing steps (_Data Processors_), their inputs and their outputs can be seen in [runBasic.cxx](https://github.com/AliceO2Group/QualityControl/blob/master/Framework/runBasic.cxx). In the QC we define the workflows in files whose names are prefixed with `run`.
+An example of a workflow definition which describes the processing steps (_Data Processors_), their inputs and their outputs can be seen in [runBasic.cxx](https://github.com/AliceO2Group/QualityControl/blob/master/Framework/src/runBasic.cxx). In the QC we define the workflows in files whose names are prefixed with `run`.
 
 ### Data Sampling
 
@@ -83,7 +83,7 @@ Data Sampling is used by Quality Control to feed the tasks with data. Below we p
 }
 ```
 
-An example of using the data sampling in a DPL workflow is visible in [runAdvanced.cxx](https://github.com/AliceO2Group/QualityControl/blob/master/Framework/runAdvanced.cxx).
+An example of using the data sampling in a DPL workflow is visible in [runAdvanced.cxx](https://github.com/AliceO2Group/QualityControl/blob/master/Framework/src/runAdvanced.cxx).
 
 #### Custom Data Sampling Condition
 
@@ -172,7 +172,7 @@ Now that there is a module, we can build it and test it. First let's build it :
 ```
 # We are in ~/alice and alienv has been called.
 # Go to the build directory of QualityControl.
-cd sw/slc7_x86-64/BUILD/QualityControl-latest/QualityControl
+cd sw/BUILD/QualityControl-latest/QualityControl
 make -j8 install # replace 8 by the number of cores on your machine
 ```
 
diff --git a/doc/QuickStart.md b/doc/QuickStart.md
@@ -19,16 +19,24 @@
 
 [↑ Go to the Table of Content ↑](../README.md) | [Continue to Modules Development →](ModulesDevelopment.md)
 
+## Read this first!
+
+This page will give you a basic idea of the QC and how to run it. Please read it *in its entirety* and run the commands along the way. Do not start developing your module before you have reached the next section called "Modules Development". Also, make sure you have pulled the latest QC version.
+
+We would be very grateful if you could report to us any error or inaccuracy you found. 
+
+Thanks!
+
 ## Requirements
 
 A Linux machine (CC7 or Ubuntu) or a Mac. See the O2 instructions below for the exact supported versions.
 
 ## Setup
 
-1. Setup O2 environment and tools <br>We use alibuild, see complete instructions [here](https://alice-doc.github.io/alice-analysis-tutorial/building/) (prefer the second option, not alidock). In particular make sure to follow these steps :
+1. Setup O2 environment and tools <br>We use alibuild, see complete instructions [here](https://alice-doc.github.io/alice-analysis-tutorial/building/) (prefer the second option, not alidock). In particular make sure to follow these steps:
    1. Install GLFW to have GUIs in the DPL (optional, **DPL GUIs do not work in containers nor over SSH**).
-        * CC7 : `sudo yum install -y glfw-devel --enablerepo=epel`
-        * Mac : `brew install glfw`
+        * CC7: `sudo yum install -y glfw-devel --enablerepo=epel`
+        * Mac: `brew install glfw`
    2. Prerequisites  
         * [CC7](https://alice-doc.github.io/alice-analysis-tutorial/building/prereq-centos7.html)
         * [Mac](https://alice-doc.github.io/alice-analysis-tutorial/building/prereq-macos.html)
@@ -43,7 +51,7 @@ A Linux machine (CC7 or Ubuntu) or a Mac. See the O2 instructions below for the
     * `aliBuild build O2Suite --defaults o2`
     * At this point you might encounter a message about missing system requirements. Run `aliDoctor O2Suite` to get a full information about what is missing and how to install it.
 
-Note : on non-CC7 systems, you can also use the alibuild "defaults" called `o2-dataflow` to avoid building simulation related packages.
+Note: on non-CC7 systems, you can also use the alibuild "defaults" called `o2-dataflow` to avoid building simulation related packages.
 
 ### Environment loading
 
@@ -65,7 +73,9 @@ To run it simply do:
 
     o2-qc-run-basic
 
-Thanks to the Data Processing Layer (DPL, more details later) it is a single process that steers all the _devices_, i.e. processes making up the workflow. A window should appear that shows a graphical representation of the workflow. The output of any of the processes is available by double clicking a box. If a box is red it means that the process has stopped, probably abnormally.
+Thanks to the Data Processing Layer (DPL, more details later) it is a single process that steers all the _devices_, i.e. processes making up the workflow. A window should appear that shows a graphical representation of the workflow if you are running locally. If you are running remotely via ssh, the DPL Debug GUI will not open. In some cases, it then requires to run with `-b`. The output of any of the processes is available by double clicking a box. If a box is red it means that the process has stopped, probably abnormally.
+
+This is not the GUI we will use to see the histograms. 
 
 ![basic-dpl-gui](images/basic-dpl-gui.png)
 
@@ -79,7 +89,7 @@ This command uses two executables. The first one contains only the _Producer (se
 
 __Repository and GUI__
 
-The data is stored in the [ccdb-test](ccdb-test.cern.ch:8080/browse) at CERN. If everything works fine you should see the objects being published in the QC web GUI (QCG) at this address : [https://qcg-test.cern.ch/?page=objectTree](https://qcg-test.cern.ch/?page=objectTree). The link brings you to the hierarchy of objects (see screenshot below). Open "/qc/TST/QcTask" (the task you are running) and click on "example" which is the name of your histogram. 
+The data is stored in the [ccdb-test](ccdb-test.cern.ch:8080/browse) at CERN. If everything works fine you should see the objects being published in the QC web GUI (QCG) at this address: [https://qcg-test.cern.ch/?page=objectTree](https://qcg-test.cern.ch/?page=objectTree). The link brings you to the hierarchy of objects (see screenshot below). Open "/qc/TST/QcTask" (the task you are running) and click on "example" which is the name of your histogram. 
 
 <!---
 The plot should be displayed on the right. If you wait a bit and hit "REFRESH NOW" in the far left menu you should see it changing from time to time (see second screenshot below). 
@@ -88,7 +98,7 @@ Please note that anyone running o2-qc-run-basic publishes the object under the s
 ![alt text](images/basic-qcg1.png)
 <!---![alt text](images/basic-qcg2.png)-->
 
-TODO add a link to the user documentation of the QCG when it is written.
+<!--- TODO add a link to the user documentation of the QCG when it is written. -->
 
 __Configuration file__
 
@@ -105,17 +115,19 @@ The configuration for the QC is made of many parameters described in an [advance
     "cycleDurationSeconds": "10",
 (...)
 ```
-Try and change the name of the task by replace `QcTask` by a name of your choice. Relaunch the workflows. You should now see the object published under a different directory in the QCG.
+Try and change the name of the task by replacing `QcTask` by a name of your choice (there are 2 places to update in the config file!). Relaunch the workflows. You should now see the object published under a different directory in the QCG.
 
 ### Readout chain
 
 In this second example, we are going to use the Readout as our data source.
 
 ![alt text](images/readout-schema.png)
 
-This workflow is a bit different from the basic one. The _Readout_ is not a DPL, nor a FairMQ, device and thus we have to have a _proxy_ to get data from it. This is the extra box going to the _Data Sampling_, which then injects data to the task. This is handled in the _Readout_ as long as you enable the corresponding configuration flag.
+This workflow is a bit different from the basic one. The _Readout_ is not a DPL, nor a FairMQ, device and thus we have to have a _proxy_ to get data from it. This is the extra box going to the _Data Sampling_, which then injects data to the task. This is handled in the _Readout_ as long as you enable the corresponding configuration flag. 
+
+The first thing is to load the environment for the readout in a new terminal: `alienv enter Readout/latest`. 
 
-To do so, open the readout config file located at `$READOUT_ROOT/etc/readout.cfg` and make sure that the following properties are correct :
+Then enable the data sampling channel in readout by opening the readout config file located at `$READOUT_ROOT/etc/readout.cfg` and make sure that the following properties are correct:
 
 ```
 # First make sure we never exit
@@ -130,12 +142,12 @@ enabled=1
 (...)
 ```
 
-Start Readout :
+Start Readout in a terminal:
 ```
 readout.exe file://$READOUT_ROOT/etc/readout.cfg
 ```
 
-Start the proxy, DataSampling and QC workflows :
+Start in another terminal the proxy, DataSampling and QC workflows:
 ```
 o2-qc-run-readout | o2-qc --config json://${QUALITYCONTROL_ROOT}/etc/readout.json
 ```
@@ -146,7 +158,7 @@ The data sampling is configured to sample 1% of the data as the readout should r
 
 The first option is to configure readout.exe to connect to a cru. Please refer to the [Readout documentation](https://github.com/AliceO2Group/Readout/blob/master/doc/README.md). 
 
-A more practical approach is to record a data file with Readout and then replay it on your development setup to develop and test your QC. The configuration options are described [here](https://github.com/AliceO2Group/Readout/blob/master/doc/configurationParameters.md), in particular : 
+A more practical approach is to record a data file with Readout and then replay it on your development setup to develop and test your QC. The configuration options are described [here](https://github.com/AliceO2Group/Readout/blob/master/doc/configurationParameters.md), in particular: 
 
 ```
 equipment-player-* 	filePath 	string 	
@@ -155,6 +167,8 @@ equipment-player-* 	preLoad 	int 	1 	If 1, data pages preloaded with file conten
 equipment-player-* 	fillPage 	int 	1 	If 1, content of data file is copied multiple time in each data page until page is full (or almost full: on the last iteration, there is no partial copy if remaining space is smaller than full file size). If 0, data file is copied exactly once in each data page.
 ```
 
+Another option is to use the program `o2-raw-file-reader-workflow` in O2 and described [here](https://github.com/AliceO2Group/AliceO2/tree/dev/Detectors/Raw#raw-data-file-reader-workflow). One can for example produce raw data with some Simulation workflow, or record it with `readout.exe`.
+
 #### Readout data format as received by the Task
 
 The header is an O2 header populated with data from the header built by the Readout. 
