Zoltan 2 Version 0.5
xml2dox.py
Go to the documentation of this file.
00001 #!/usr/bin/python
00002 #
00003 # Element is available in python 1.5.2 and higher.
00004 # It can be downloaded to use with older python.
00005 #
00006 # This script reads an XML description of the Zoltan2 parameters, 
00007 # and writes a doxygen page with this information.
00008 
00009 import elementtree.ElementTree as ET
00010 
00011 outfile = open("parameters.dox", "w")
00012 
00013 def parameterDocumentationHeader():
00014   outfile.write("/*! \\page z2_parameters Zoltan2 Parameters\n\n")
00015   outfile.write("This page lists each Zoltan2 parameter and how to use it.  The validators\n")
00016   outfile.write("are classes of interest to Zoltan2 developers.  They are used to evaluate\n")
00017   outfile.write("the validity of parameter values at run time.\n\n")
00018 
00019 def parameterDocumentationFooter():
00020   outfile.write("*/\n")
00021 
00022 def parameterEnhancedNumber(pname, pinfo, pval):
00023   desc = pinfo.get("docString")
00024   min = pval.get("min")
00025   max = pval.get("max")
00026   step = pval.get("step")
00027 
00028   outfile.write("- \\b "+pname+" \\anchor "+pname+"\n")
00029   outfile.write("  - Description: "+desc+"\n")
00030   outfile.write("  - Valid values:\n")
00031   outfile.write("     - minimum is "+min+"\n")
00032   outfile.write("     - maximum is "+max+"\n")
00033   outfile.write("     - step is "+step+"\n")
00034   outfile.write("  - Validator type: Teuchos::EnhancedNumberValidator\n")
00035   outfile.write("\n")
00036 
00037 def parameterIntegerRangeList(pname, pinfo, pval):
00038   desc = pinfo.get("docString")
00039   unsorted = pval.get("unsorted")
00040   min="unset"
00041   max="unset"
00042   if "min" in pinfo.keys():
00043     min = pval.get("min")
00044   if "max" in pinfo.keys():
00045     max = pval.get("max")
00046 
00047   outfile.write("- \\b "+pname+" \\anchor "+pname+"\n")
00048   outfile.write("  - Description: "+desc+"\n")
00049   outfile.write("  - Valid values: a comma-separated list of\n")
00050   outfile.write("     - numbers\n")
00051   outfile.write("     - number ranges separated by a dash (\"1-5\")\n")
00052   outfile.write("     - the word \"all\" to indicate all possible values\n")
00053   if min != "unset":
00054     outfile.write("     - minimum is: "+min+"\n")
00055   if max != "unset":
00056     outfile.write("     - maximum is: "+max+"\n")
00057 
00058   outfile.write("  - Examples: \"1,2,7\", \"all\", \"5,1-15,80-82,99\"\n")
00059   outfile.write("  - Validator type: Zoltan2::IntegerRangeListValidator\n")
00060   if unsorted == "true":
00061     outfile.write(      "(list is not changed during processing)\n")
00062   else:
00063     outfile.write(      "(list will be sorted, and duplicates removed, during processing)\n")
00064 
00065   outfile.write("\n")
00066 
00067 def parameterFileName(pname, pinfo, pval):
00068   desc = pinfo.get("docString")
00069   outfile.write("- \\b "+pname+" \\anchor "+pname+"\n")
00070   outfile.write("  - Description: "+desc+"\n")
00071   outfile.write("  - Validator type: Teuchos::FileNameValidator\n")
00072   outfile.write("\n")
00073 
00074 def parameterAnyNumber(pname, pinfo, pval):
00075   desc = pinfo.get("docString")
00076   validTypes = []
00077   if pval.get("allowDouble") == "true":
00078     validTypes.append("double")
00079   if pval.get("allowInt") == "true":
00080     validTypes.append("int")
00081   if pval.get("allowString") == "true":
00082     validTypes.append("string")
00083 
00084   outfile.write("- \\b "+pname+" \\anchor "+pname+"\n")
00085   outfile.write("  - Description: "+desc+"\n")
00086   outfile.write("  - Valid values are any values of type:\n")
00087   for vtype in validTypes:
00088     outfile.write("      \\li "+vtype+"\n")
00089   outfile.write("  - Validator type: Teuchos::AnyNumberParameterEntryValidator\n")
00090   outfile.write("\n")
00091 
00092 def parameterStringToIntegral(pname, pinfo, pval):
00093   desc = pinfo.get("docString")
00094   outfile.write("- \\b "+pname+" \\anchor "+pname+"\n")
00095   outfile.write("  - Description: "+desc+"\n")
00096   outfile.write("  - Valid values:\n")
00097   for node in pval:
00098     if node.tag == "String":
00099       svalue = node.get("stringValue")
00100       sdoc = "unset"
00101       if "stringDoc" in node.keys():
00102         sdoc = node.get("stringDoc")
00103       if sdoc == "unset":
00104         outfile.write("    \\li \\e "+svalue+"\n")
00105       else:
00106         outfile.write("    \\li \\e "+svalue+" "+sdoc+"\n")
00107   outfile.write("  - Validator type: Teuchos::StringToIntegralParameterEntryValidator\n")
00108   outfile.write("\n")
00109 
00110 def parameterFileName(pname, pinfo, pval):
00111   desc = pinfo.get("docString")
00112   mustExist = pinfo.get("fileMustExist")
00113   outfile.write("- \\b "+pname+" \\anchor "+pname+"\n")
00114   outfile.write("  - Description: "+desc+"\n")
00115   if mustExist == "true":
00116     outfile.write("  File must exist.\n")
00117   else:
00118     outfile.write("  File need not already exist.\n")
00119   outfile.write("  - Validator type: Teuchos::FileNameValidator\n")
00120   outfile.write("\n")
00121 
00122 def parameterString(pname, pinfo, pval):
00123   desc = pinfo.get("docString")
00124   outfile.write("- \\b "+pname+" \\anchor "+pname+"\n")
00125   outfile.write("  - Description: "+desc+"\n")
00126   outfile.write("  - Valid values:\n")
00127   for node in pval:
00128     if node.tag == "String":
00129       outfile.write("    \\li \\e "+node.get("value")+"\n")
00130   outfile.write("  - Validator type: Teuchos::StringValidator\n")
00131   outfile.write("\n")
00132 
00133 def writeInfo(param):
00134   pname = param[0]
00135   pinfo = param[1]
00136   pval = param[2]
00137 
00138   pvalidatorType = pval.get("type")
00139   
00140   if pvalidatorType == "anynumberValidator":
00141     parameterAnyNumber(pname, pinfo, pval)
00142 
00143   elif pvalidatorType == "FilenameValidator":
00144     parameterFileName(pname, pinfo, pval)
00145 
00146   elif pvalidatorType == "StringValidator":
00147     parameterString(pname, pinfo, pval)
00148 
00149   elif "StringIntegralValidator" in pvalidatorType:
00150     parameterStringToIntegral(pname, pinfo, pval)
00151 
00152   elif "IntegerRangeListValidator" in pvalidatorType:
00153     parameterIntegerRangeList(pname, pinfo, pval)
00154 
00155   elif "EnhancedNumberValidator" in pvalidatorType:
00156     parameterEnhancedNumber(pname, pinfo, pval)
00157 
00158   else:
00159     print "Error 4: This is not a valid Zoltan2 parameter list."
00160     exit
00161 
00162 ##
00163 ## Begin
00164 ##
00165 
00166 tree = ET.parse("../data/parameters.xml")
00167 
00168 root = tree.getroot()
00169 
00170 if root.tag != "ParameterList":
00171   print "Error 1: This is not a valid Zoltan2 parameter list."
00172   exit
00173 
00174 validators = []
00175 for node in root:
00176   if node.tag == "Validators":
00177     validators = node
00178     break
00179 
00180 if len(validators) == 0:
00181   print "Error 1: This is not a valid Zoltan2 parameter list."
00182   exit
00183 
00184 # Create a dictionary of Validators
00185 
00186 vals={}
00187 
00188 for node in validators:
00189   id = node.get("validatorId")
00190   vals[id] = node 
00191 
00192 ##
00193 # Create list of a 3-tuples for each parameter, including
00194 # the parameter name, its data, and its validator.
00195 ##
00196 
00197 parameterInfo = []
00198 
00199 for node in root:
00200   if node.tag != "Parameter":
00201     continue
00202   id = node.get("validatorId")
00203   if id not in vals.keys():
00204     print "Error 3: This is not a valid Zoltan2 parameter list."
00205     exit
00206 
00207   paramName = node.get("name")
00208 
00209   parameterInfo.append((paramName, node, vals[id]))
00210   
00211 ##
00212 # Write the doxygen documentation for these parameters
00213 ##
00214 
00215 parameterDocumentationHeader()
00216 
00217 for info in sorted(set(parameterInfo)):
00218   print "Parameter: ",info[0]
00219   writeInfo(info)
00220 
00221 parameterDocumentationFooter()
00222 
00223 outfile.close()
00224   
00225