Implemented customization of help messages of the DPL driver app

An optional argument can be specified to the `--help,-h` option, to create
different versions of the help printout:
- `full`: the full printout with executor, workflow and processor options
- `short`: executor and workflow options, as well as a summary of the processors
- `workflow`: workflow options only
- `executor`: executor options only
- by specifying a valid name for a process which defines option, its options are printed

Default behaviour is `short`.

The definition of processors might depend on the specified workflow options. The help
message is adjusted to workflow options if specified in addition to the `--help` option.

Author: matthiasrichter

Framework/Core/include/Framework/ConfigParamsHelper.h

@@ -42,39 +42,59 @@ struct ConfigParamsHelper
                                        );
 
   /// populate boost program options for a complete workflow
-  template<typename ContainerType>
+  template <typename ContainerType>
   static boost::program_options::options_description
-  prepareOptionDescriptions(const ContainerType &workflow,
-                            const std::vector<ConfigParamSpec> &workflowOptions,
-                            options_description vetos = options_description()
-                            )
+    prepareOptionDescriptions(const ContainerType& workflow,
+                              const std::vector<ConfigParamSpec>& workflowOptions,
+                              options_description vetos = options_description(),
+                              std::string mode = "full")
   {
     boost::program_options::options_description toplevel;
     boost::program_options::options_description wo("Global workflow options");
     if (prepareOptionsDescription(workflowOptions, wo, vetos)) {
       toplevel.add(wo);
     }
-    boost::program_options::options_description specOptions("Available data processors");
+    std::string specOptionsDescription = "Available data processors";
+    if (mode == "short") {
+      specOptionsDescription += " (full info with '--help full')";
+    }
+    options_description specOptions(specOptionsDescription);
     for (const auto & spec : workflow) {
-      std::string help = "Usage: --" + spec.name + R"( "<data processor options>")";
-      specOptions.add_options()(spec.name.c_str(),
-                                boost::program_options::value<std::string>(),
-                                help.c_str());
       std::string name = "Data processor options: " + spec.name;
-      boost::program_options::options_description options(name);
-      if (prepareOptionsDescription(spec.options, options, vetos)) {
-        specOptions.add(options);
+      boost::program_options::options_description processorOptions(name);
+      if (prepareOptionsDescription(spec.options, processorOptions, vetos)) {
         // if vetos have been provided to the function we also need to make
         // sure that there are no duplicate option definitions for the individual
         // processor specs, so we add in order to be vetos for all subsequent specs.
         // Note: this only concerns the main parser, all individual options are
         // handled when starting individual processors.
         if (vetos.options().size() > 0) {
-          vetos.add(options);
+          vetos.add(processorOptions);
+        }
+        if (mode == "full") {
+          specOptions.add(processorOptions);
+        } else if (mode == spec.name) {
+          toplevel.add(processorOptions);
+          break;
         }
       }
+      if (mode == "full" || mode == "short") {
+        std::string help;
+        if (mode == "full") {
+          help = "Option groups by process name: --" + spec.name + R"( "<processor options>")";
+        } else if (mode == "short" && processorOptions.options().size() > 0) {
+          help = "Use '--help " + spec.name + "' to display processor options";
+        } else if (mode == "short" && processorOptions.options().size() == 0) {
+          help = "No processor options";
+        }
+        specOptions.add_options()(spec.name.c_str(),
+                                  boost::program_options::value<std::string>(),
+                                  help.c_str());
+      }
+    }
+    if (workflow.size() > 0 && (mode == "full" || mode == "short")) {
+      toplevel.add(specOptions);
     }
-    toplevel.add(specOptions);
     return toplevel;
   }
 

Framework/Core/src/runDataProcessing.cxx

@@ -1012,8 +1012,9 @@ int doMain(int argc, char** argv, o2::framework::WorkflowSpec const& workflow,
 {
   enum TerminationPolicy policy;
   bpo::options_description executorOptions("Executor options");
+  const char* helpDescription = "print help: short, full, executor, or processor name";
   executorOptions.add_options()                                                                             //
-    ("help,h", "print this help")                                                                           //
+    ("help,h", bpo::value<std::string>()->implicit_value("short"), helpDescription)                         //
     ("quiet,q", bpo::value<bool>()->zero_tokens()->default_value(false), "quiet operation")                 //
     ("stop,s", bpo::value<bool>()->zero_tokens()->default_value(false), "stop before device start")         //
     ("single-step", bpo::value<bool>()->zero_tokens()->default_value(false), "start in single step mode")   //
@@ -1061,11 +1062,35 @@ int doMain(int argc, char** argv, o2::framework::WorkflowSpec const& workflow,
   }
 
   if (varmap.count("help")) {
+    auto mode = varmap["help"].as<std::string>();
     bpo::options_description helpOptions;
-    helpOptions.add(executorOptions);
+    if (mode == "full" || mode == "short" || mode == "executor") {
+      helpOptions.add(executorOptions);
+    }
     // this time no veto is applied, so all the options are added for printout
-    helpOptions.add(ConfigParamsHelper::prepareOptionDescriptions(physicalWorkflow, workflowOptions));
-    std::cout << helpOptions << std::endl;
+    if (mode == "executor") {
+      // nothing more
+    } else if (mode == "workflow") {
+      // executor options and workflow options, skip the actual workflow
+      o2::framework::WorkflowSpec emptyWorkflow;
+      helpOptions.add(ConfigParamsHelper::prepareOptionDescriptions(emptyWorkflow, workflowOptions));
+    } else if (mode == "full" || mode == "short") {
+      helpOptions.add(ConfigParamsHelper::prepareOptionDescriptions(physicalWorkflow, workflowOptions,
+                                                                    bpo::options_description(),
+                                                                    mode));
+    } else {
+      helpOptions.add(ConfigParamsHelper::prepareOptionDescriptions(physicalWorkflow, {},
+                                                                    bpo::options_description(),
+                                                                    mode));
+    }
+    if (helpOptions.options().size() == 0) {
+      // the specified argument is invalid, add at leat the executor options
+      mode += " is an invalid argument, please use correct argument for";
+      helpOptions.add(executorOptions);
+    }
+    std::cout << "ALICE O2 DPL workflow driver"        //
+              << " (" << mode << " help)" << std::endl //
+              << helpOptions << std::endl;             //
     exit(0);
   }