Merge branch 'erodrigu-rename-run_davinci' into 'master'

Better documentation for master function run_davinci

See merge request !604

DaVinciSys/scripts/davinci

@@ -27,7 +27,7 @@ A DaVinci job using simulated data can be run using the command line:
 
 import os, sys, click
 from DaVinci.utilities_script import dump_call, get_configurable_opts, set_testfiledb
-from DaVinci.ConfigurationUpgrade import run_davinci
+from DaVinci.ConfigurationUpgrade import run_davinci_app
 from DaVinci.config import options
 from DaVinci.optionChecker import log_click
 
@@ -168,7 +168,7 @@ def run_mc(ctx, inputfiledb, joboptfile, simplejob):
     ctx_args = (ctx.args if (len(ctx.args) > 1) else [])
     dump_call(inputfiledb_file, inputfiledb_key, joboptfile, ctx_args)
 
-    config = run_davinci(
+    config = run_davinci_app(
         inputfiledb_key,
         inputfiledb_file,  #file and key for job input and conditions
         joboptfile,  # file for job options
@@ -223,7 +223,7 @@ def run_data(ctx, inputfiledb, optfile):
     ctx_args = (ctx.args if (len(ctx.args) > 1) else [])
     dump_call(inputfiledb_file, inputfiledb_key, joboptfile, ctx_args)
 
-    config = run_davinci(
+    config = run_davinci_app(
         inputfiledb_key,
         inputfiledb_file,  #file and key for job input and conditions
         joboptfile,  # file for job options

DaVinciTests/tests/options/prod_conf/options_reference.py

@@ -9,7 +9,7 @@
 # or submit itself to any jurisdiction.                                       #
 ###############################################################################
 from DaVinci import options
-from DaVinci.ConfigurationUpgrade import run_davinci
+from DaVinci.ConfigurationUpgrade import run_davinci_app
 from DaVinci.compat.tests.params import prod_conf_params
 
 options.conddb_tag = prod_conf_params["CondDBTag"]
@@ -17,4 +17,4 @@ options.dddb_tag = prod_conf_params["DDDBTag"]
 options.evt_max = prod_conf_params["NOfEvents"]
 options.input_files = prod_conf_params["InputFiles"]
 
-run_davinci(prod_conf=True)
+run_davinci_app(prod_conf=True)

Phys/DaVinci/python/DaVinci/ConfigurationUpgrade.py

@@ -20,16 +20,68 @@ from DaVinci.algorithms import (setup_algorithms, define_fsr_writer,
 from DaVinci.config import davinci_control_flow, prepare_davinci_nodes
 
 
+def run_davinci_app(fileDB_key="",
+                    fileDB_file="",
+                    jobOpt_file="",
+                    ctx_args=[],
+                    simple_job=False,
+                    prod_conf=False):
+    """
+    Run the DaVinci application.
+
+    This is the "master function" called
+
+    - by the `davinci` executable in DaVinciSys/scripts.
+    - by the `DaVinci` legacy configurable in `DaVinci/compat/DaVinciConf.py`
+      for running DaVinci in production via `ProdConf`.
+    - directly by the user, typically for simple jobs, when invoking `./run gaudirun.py`.
+
+    Args:
+        fileDB_key (str, optional): key in the testfileDB. Defaults to "".
+        fileDB_file (str, optional): file with the testfileDB. Defaults to "".
+        jobOpt_file (str, optional): file containing the options to be used for running the job.
+             Defaults to "".
+        ctx_args (iterable, optional): click context containing all the extra options.
+             Defaults to [].
+        simple_job (bool, optional): flag for running job using only the PyConf configurations.
+             Defaults to False.
+        prod_conf (bool, optional): flag for running DaVinci with ProdConf.
+             Defaults to False.
+
+    Returns:
+        ComponentConfig instance, a dict of configured Configurable instances.
+    """
+    from DaVinci import options
+
+    if fileDB_key and not prod_conf:
+        set_input_file_options(options, fileDB_key, fileDB_file)
+    if jobOpt_file:
+        set_job_options(options, jobOpt_file, fileDB_key, fileDB_file)
+    if ctx_args:
+        set_args_options(options, ctx_args, fileDB_key, fileDB_file)
+
+    config = ComponentConfig()
+
+    if simple_job:
+        config.update(add_simple_conf(options))
+    else:
+        config.update(add_davinci_configurables(options))
+
+    if not prod_conf:
+        return config
+
+
 def add_davinci_configurables(options):
     """
     Run the job adding the specific Davinci configurables to the standard PyConf ones.
+
     Algorithms developed by users are also included.
 
     Args:
-       - options: list of DV options.
+        options (DVAppOptions instance): list of DV options.
 
     Returns:
-       - ComponentConfig: Dict of configured Gaudi and DaVinci Configurable instances and user algorithms.
+        ComponentConfig instance, a dict of configured Gaudi and DaVinci Configurable instances and user algorithms.
     """
     dvMainFlow = {}
     fsrAlgs = {}
@@ -64,10 +116,10 @@ def add_simple_conf(options):
     Run the job using only the standard PyConf configuration with any user algorithm.
 
     Args:
-       - options: list of DV options.
+        options (DVAppOptions instance): list of DV options.
 
     Returns:
-       - ComponentConfig: Dict of configured Gaudi Configurable instances and user algorithms.
+        ComponentConfig instance, a dict of configured Gaudi Configurable instances and user algorithms.
     """
     userAlgs, publicTools = setup_algorithms(options)
 
@@ -80,43 +132,3 @@ def add_simple_conf(options):
     config.update(configure(options, top_dv_node, public_tools=publicTools))
 
     return config
-
-
-def run_davinci(fileDB_key="",
-                fileDB_file="",
-                jobOpt_file="",
-                ctx_args=[],
-                simple_job=False,
-                prod_conf=False):
-    """
-    Run DaVinci application.
-
-    Args:
-       - fileDB_key: key in the testfileDB.
-       - fileDB_file: file with the testfileDB.
-       - jobOpt_file: file containing the options to be used for running the job.
-       - ctx_args: click context containing all the extra options.
-       - simple_job: flag for running job using only the PyConf configurations.
-       - prod_conf: flag for running DaVinci with ProdConf.
-
-    Returns:
-       - ComponentConfig: Dict of configured Configurable instances.
-    """
-    from DaVinci import options
-
-    if fileDB_key and not prod_conf:
-        set_input_file_options(options, fileDB_key, fileDB_file)
-    if jobOpt_file:
-        set_job_options(options, jobOpt_file, fileDB_key, fileDB_file)
-    if ctx_args:
-        set_args_options(options, ctx_args, fileDB_key, fileDB_file)
-
-    config = ComponentConfig()
-
-    if simple_job:
-        config.update(add_simple_conf(options))
-    else:
-        config.update(add_davinci_configurables(options))
-
-    if not prod_conf:
-        return config

Phys/DaVinci/python/DaVinci/compat/DaVinciConf.py

@@ -15,7 +15,7 @@ import re
 from Gaudi.Configuration import appendPostConfigAction
 from Configurables import (LHCbApp, EventSelector, DDDBConf, CondDB,
                            LHCbConfigurableUser, HistogramPersistencySvc)
-from DaVinci.ConfigurationUpgrade import run_davinci
+from DaVinci.ConfigurationUpgrade import run_davinci_app
 from DaVinci.configOptions import set_option_value
 from DaVinci import options
 
@@ -121,7 +121,7 @@ class DaVinci(LHCbConfigurableUser):
         """
         Run the DaVinci configuration.
         """
-        run_davinci(prod_conf=True)
+        run_davinci_app(prod_conf=True)
 
     def __apply_configuration__(self):
         """