Added script which allows automatic update of O2 data model documentation

scripts/datamodel-doc/ALICEO2dataModel.py

@@ -456,6 +456,24 @@ def printHTML(self):
     else:
       tmp = tmp.text.strip()
     O2href = tmp
+    tmp = self.initCard.find("O2general/delimAO2D")
+    if tmp == None:
+      tmp = ""
+    else:
+      tmp = tmp.text.strip()
+    delimAO2D = tmp
+    tmp = self.initCard.find("O2general/delimHelpers")
+    if tmp == None:
+      tmp = ""
+    else:
+      tmp = tmp.text.strip()
+    delimHelpers = tmp
+    tmp = self.initCard.find("O2general/delimJoins")
+    if tmp == None:
+      tmp = ""
+    else:
+      tmp = tmp.text.strip()
+    delimJoins = tmp
 
     # gather all tables and columns
     tabs = list()
@@ -476,9 +494,14 @@ def printHTML(self):
       if len(inds) == 0:
         continue
 
-      if amFirst == False and HTheaderToWrite == True:
-        self.printHTheaderHTML()
-        HTheaderToWrite = False
+      if amFirst == True:
+        print(delimAO2D)
+      else:
+        if HTheaderToWrite == True:
+          print(delimAO2D)
+          print("")
+          print(delimHelpers)
+          HTheaderToWrite = False
 
       print("")
       print("#### ", CErelation[2])
@@ -562,7 +585,10 @@ def printHTML(self):
       amFirst = False
 
     # now print the usings
+    print(delimHelpers)
     if len(uses) > 0:
+      print("")
+      print(delimJoins)
       print("")
       print("<a name=\"usings\"></a>")
       print("## List of defined joins and iterators")
@@ -577,15 +603,7 @@ def printHTML(self):
         print("    </ul>")
         print("  </div>")
       print("</div>")
-
-  def printHTheaderHTML(self):
-    print("")
-    print("<a name=""helper_tasks""></a>")
-    print("## List of tables created with helper tasks")
-    print("")
-    print("The AO2D data files contain the basic set of data which is available for data analysis and from which other quantities are deduced. There are however quantities like PID information, V0 characteristics, etc. which are commonly used in analysis. In order to prevent that tasks to compute such quantities are repeatingly developed, a set of helper tasks is provided by the O2 framework. These tasks are listed below together with the tables they provide.")
-    print("")
-    print("Click on the labels to display the table details.")
+      print(delimJoins)
 
 # -----------------------------------------------------------------------------
 # functions

scripts/datamodel-doc/README.md

@@ -74,3 +74,31 @@ Set the path in tag data/O2general/mainDir/local to the actual O2 installation p
 ./extractDataModel.py > htmloutput.txt
 
 - Update the markdown files with the content of htmloutput.txt.
+
+
+### Update the markdown files automatically
+
+The python script mdUpdate.py allows to update the contents of the md files automatically.
+
+mdUpdate.py takes four arguments:
+
+Usage:
+mdUpdate.py cc fn2u fnold fnnew
+
+cc: 1: AO2D, 2: Helpers, 3: Joins
+
+fn2u: file with new text
+
+fnold: file with old text
+
+fnnew: file with replaced text
+
+mdUpdate.py replaces in file fnold the block of text which is delimited by two lines containing a delimiter string by the block of text in file fn2u which is delimited by two lines containing the same delimiter string and write the output to file fnnew. The delimiter string is obtained from the inputCard.xml, depending on the value of cc. If fnnew = fnold, the content of fnold is overwritten.
+
+So to update the md files do:
+
+- ./extractDataModel.py > htmloutput.txt
+- path2mds=./testing
+- ./mdUpdate.py 1 htmloutput.txt $path2mds/ao2dTables.md $path2mds/ao2dTables.md
+- ./mdUpdate.py 2 htmloutput.txt $path2mds/helperTaskTables.md $path2mds/helperTaskTables.md
+- ./mdUpdate.py 3 htmloutput.txt $path2mds/joinsAndIterators.md $path2mds/joinsAndIterators.md

scripts/datamodel-doc/inputCard.xml

@@ -46,6 +46,19 @@
       o2_add_dpl_workflow
     </CEdeclarationString>
 
+    <!-- delimiters used to mark text blocks to be replaced in html files -->
+    <delimAO2D>
+      &lt;!-- Block with AO2D tables --&gt;
+    </delimAO2D>
+
+    <delimHelpers>
+      &lt;!-- Block with helper tasks --&gt;
+    </delimHelpers>
+
+    <delimJoins>
+      &lt;!-- Block with joins and iterators --&gt;
+    </delimJoins>
+
   </O2general>
 
 

scripts/datamodel-doc/mdUpdate.py

@@ -0,0 +1,125 @@
+#!/usr/bin/python3.6
+
+import sys
+import xml.etree.ElementTree as ET
+
+# -----------------------------------------------------------------------------
+# replace the text between two lines starting with 'delimiter' in file 'fold'
+# by the text between two lines starting with 'delimiter' in file 'ftouse'.
+# Write new content into 'fnew' and keep the lines with the 'delimiter'.
+
+# -----------------------------------------------------------------------------
+# get text in file 'fn' beteween the lines starting with 'delimiter'
+def blockbtwdelims (fn, delimiter):
+  blck = []
+
+  cnt = 0
+  with open(fn) as f:
+    for line in f:
+      if line.startswith(delimiter):
+        blck.append(line.rstrip())
+        if cnt > 0:
+          break
+        cnt += 1
+      else:
+        if cnt > 0:
+          blck.append(line.rstrip())
+
+  return blck
+
+# -----------------------------------------------------------------------------
+# get text in file 'fn' before any line starting with 'delimiter'
+def blockbefdelims (fn, delimiter):
+  blck = []
+
+  with open(fn) as f:
+    for line in f:
+      if line.startswith(delimiter):
+        break
+      blck.append(line.rstrip())
+
+  return blck
+
+# -----------------------------------------------------------------------------
+# get text in file 'fn' after the text block delimited by lines starting with
+# 'delimiter'
+def blockaftdelims (fn, delimiter):
+  blck = []
+
+  cnt = 0
+  with open(fn) as f:
+    for line in f:
+      if line.startswith(delimiter):
+        if cnt < 2:
+          cnt += 1
+          continue
+
+      if cnt > 1:
+        blck.append(line.rstrip())
+
+  return blck
+
+# -----------------------------------------------------------------------------
+# concatenate two blocks of text
+def addblocks(b0, b1):
+  b2 = b0
+  for l in b1:
+    b2.append(l.rstrip())
+
+  return b2
+
+# -----------------------------------------------------------------------------
+def main(initCard):
+
+  if len(sys.argv) < 4:
+    print ("Wrong number of arguments!")
+    print ("Usage:")
+    print ("  purger.py cc fn2u fnold fnnew")
+    print ("")
+    print ("    cc: 1: AO2D, 2: Helpers, 3: Joins")
+    print ("    fn2u: file with new text")
+    print ("    fnold: file with old text")
+    print ("    fnnew: file with replaced text")
+    print ("")
+    exit()
+
+  cc = int(sys.argv[1])
+  fntouse = sys.argv[2]
+  fnold = sys.argv[3]
+  fnnew = sys.argv[4]
+
+  # get the 'delimiter' from initCard
+  tmp = None
+  if cc == 1:
+    tmp = initCard.find("O2general/delimAO2D")
+  elif cc == 2:
+    tmp = initCard.find("O2general/delimHelpers")
+  elif cc == 3:
+    tmp = initCard.find("O2general/delimJoins")
+  else:
+    exit()
+  delimiter = tmp.text.strip()
+  print("Replacing ",delimiter)
+
+  # get replacement
+  b2u = blockbtwdelims(fntouse, delimiter)
+  if len(b2u) == 0:
+    exit()
+
+  # entire new text
+  bnew = addblocks(blockbefdelims(fnold, delimiter), b2u)
+  bnew = addblocks(bnew, blockaftdelims(fnold, delimiter))
+
+  # write new text to fnnew
+  with open(fnnew, 'w') as f:
+    for l in bnew:
+      print(l, file=f)
+
+# -----------------------------------------------------------------------------
+if __name__ == "__main__":
+
+  initCard = ET.parse("inputCard.xml")
+
+  main(initCard)
+
+# -----------------------------------------------------------------------------