Zoltan2
 All Namespaces Files Functions Variables Pages
xml2dox.py
Go to the documentation of this file.
1 #!/usr/bin/python
2 #
3 # xml.etree.ElementTree is available in python 2.5 and higher.
4 # It can be downloaded to use with older python.
5 #
6 # This script reads an XML description of the Zoltan2 parameters,
7 # and writes a doxygen page with this information.
8 
9 import xml.etree.ElementTree as ET
10 
11 outfile = open("parameters.dox", "w")
12 
14  outfile.write("/*! \\page z2_parameters Zoltan2 Parameters\n\n")
15  outfile.write("This page lists each Zoltan2 parameter and how to use it. The validators\n")
16  outfile.write("are classes of interest to Zoltan2 developers. They are used to evaluate\n")
17  outfile.write("the validity of parameter values at run time.\n\n")
18 
20  outfile.write("*/\n")
21 
22 def parameterEnhancedNumber(pname, pinfo, pval):
23  desc = pinfo.get("docString")
24  min = pval.get("min")
25  max = pval.get("max")
26  step = pval.get("step")
27 
28  outfile.write("- \\b "+pname+" \\anchor "+pname+"\n")
29  outfile.write(" - Description: "+desc+"\n")
30  outfile.write(" - Valid values:\n")
31  outfile.write(" - minimum is "+min+"\n")
32  outfile.write(" - maximum is "+max+"\n")
33  outfile.write(" - step is "+step+"\n")
34  outfile.write(" - Validator type: Teuchos::EnhancedNumberValidator\n")
35  outfile.write("\n")
36 
37 def parameterIntegerRangeList(pname, pinfo, pval):
38  desc = pinfo.get("docString")
39  unsorted = pval.get("unsorted")
40  min="unset"
41  max="unset"
42  if "min" in pinfo.keys():
43  min = pval.get("min")
44  if "max" in pinfo.keys():
45  max = pval.get("max")
46 
47  outfile.write("- \\b "+pname+" \\anchor "+pname+"\n")
48  outfile.write(" - Description: "+desc+"\n")
49  outfile.write(" - Valid values: a comma-separated list of\n")
50  outfile.write(" - numbers\n")
51  outfile.write(" - number ranges separated by a dash (\"1-5\")\n")
52  outfile.write(" - the word \"all\" to indicate all possible values\n")
53  if min != "unset":
54  outfile.write(" - minimum is: "+min+"\n")
55  if max != "unset":
56  outfile.write(" - maximum is: "+max+"\n")
57 
58  outfile.write(" - Examples: \"1,2,7\", \"all\", \"5,1-15,80-82,99\"\n")
59  outfile.write(" - Validator type: Zoltan2::IntegerRangeListValidator\n")
60  if unsorted == "true":
61  outfile.write( "(list is not changed during processing)\n")
62  else:
63  outfile.write( "(list will be sorted, and duplicates removed, during processing)\n")
64 
65  outfile.write("\n")
66 
67 def parameterFileName(pname, pinfo, pval):
68  desc = pinfo.get("docString")
69  outfile.write("- \\b "+pname+" \\anchor "+pname+"\n")
70  outfile.write(" - Description: "+desc+"\n")
71  outfile.write(" - Validator type: Teuchos::FileNameValidator\n")
72  outfile.write("\n")
73 
74 def parameterAnyNumber(pname, pinfo, pval):
75  desc = pinfo.get("docString")
76  validTypes = []
77  if pval.get("allowDouble") == "true":
78  validTypes.append("double")
79  if pval.get("allowInt") == "true":
80  validTypes.append("int")
81  if pval.get("allowString") == "true":
82  validTypes.append("string")
83 
84  outfile.write("- \\b "+pname+" \\anchor "+pname+"\n")
85  outfile.write(" - Description: "+desc+"\n")
86  outfile.write(" - Valid values are any values of type:\n")
87  for vtype in validTypes:
88  outfile.write(" \\li "+vtype+"\n")
89  outfile.write(" - Validator type: Teuchos::AnyNumberParameterEntryValidator\n")
90  outfile.write("\n")
91 
92 def parameterStringToIntegral(pname, pinfo, pval):
93  desc = pinfo.get("docString")
94  outfile.write("- \\b "+pname+" \\anchor "+pname+"\n")
95  outfile.write(" - Description: "+desc+"\n")
96  outfile.write(" - Valid values:\n")
97  for node in pval:
98  if node.tag == "String":
99  svalue = node.get("stringValue")
100  sdoc = "unset"
101  if "stringDoc" in node.keys():
102  sdoc = node.get("stringDoc")
103  if sdoc == "unset":
104  outfile.write(" \\li \\e "+svalue+"\n")
105  else:
106  outfile.write(" \\li \\e "+svalue+" "+sdoc+"\n")
107  outfile.write(" - Validator type: Teuchos::StringToIntegralParameterEntryValidator\n")
108  outfile.write("\n")
109 
110 def parameterFileName(pname, pinfo, pval):
111  desc = pinfo.get("docString")
112  mustExist = pinfo.get("fileMustExist")
113  outfile.write("- \\b "+pname+" \\anchor "+pname+"\n")
114  outfile.write(" - Description: "+desc+"\n")
115  if mustExist == "true":
116  outfile.write(" File must exist.\n")
117  else:
118  outfile.write(" File need not already exist.\n")
119  outfile.write(" - Validator type: Teuchos::FileNameValidator\n")
120  outfile.write("\n")
121 
122 def parameterString(pname, pinfo, pval):
123  desc = pinfo.get("docString")
124  outfile.write("- \\b "+pname+" \\anchor "+pname+"\n")
125  outfile.write(" - Description: "+desc+"\n")
126  outfile.write(" - Valid values:\n")
127  for node in pval:
128  if node.tag == "String":
129  outfile.write(" \\li \\e "+node.get("value")+"\n")
130  outfile.write(" - Validator type: Teuchos::StringValidator\n")
131  outfile.write("\n")
132 
133 def writeInfo(param):
134  pname = param[0]
135  pinfo = param[1]
136  pval = param[2]
137 
138  pvalidatorType = pval.get("type")
139 
140  if pvalidatorType == "anynumberValidator":
141  parameterAnyNumber(pname, pinfo, pval)
142 
143  elif pvalidatorType == "FilenameValidator":
144  parameterFileName(pname, pinfo, pval)
145 
146  elif pvalidatorType == "StringValidator":
147  parameterString(pname, pinfo, pval)
148 
149  elif "StringIntegralValidator" in pvalidatorType:
150  parameterStringToIntegral(pname, pinfo, pval)
151 
152  elif "IntegerRangeListValidator" in pvalidatorType:
153  parameterIntegerRangeList(pname, pinfo, pval)
154 
155  elif "EnhancedNumberValidator" in pvalidatorType:
156  parameterEnhancedNumber(pname, pinfo, pval)
157 
158  else:
159  print "Error 4: This is not a valid Zoltan2 parameter list."
160  exit
161 
162 ##
163 ## Begin
164 ##
165 
166 tree = ET.parse("../data/parameters.xml")
167 
168 root = tree.getroot()
169 
170 if root.tag != "ParameterList":
171  print "Error 1: This is not a valid Zoltan2 parameter list."
172  exit
173 
174 validators = []
175 for node in root:
176  if node.tag == "Validators":
177  validators = node
178  break
179 
180 if len(validators) == 0:
181  print "Error 1: This is not a valid Zoltan2 parameter list."
182  exit
183 
184 # Create a dictionary of Validators
185 
186 vals={}
187 
188 for node in validators:
189  id = node.get("validatorId")
190  vals[id] = node
191 
192 ##
193 # Create list of a 3-tuples for each parameter, including
194 # the parameter name, its data, and its validator.
195 ##
196 
197 parameterInfo = []
198 
199 for node in root:
200  if node.tag != "Parameter":
201  continue
202  id = node.get("validatorId")
203  if id not in vals.keys():
204  print "Error 3: This is not a valid Zoltan2 parameter list."
205  exit
206 
207  paramName = node.get("name")
208 
209  parameterInfo.append((paramName, node, vals[id]))
210 
211 ##
212 # Write the doxygen documentation for these parameters
213 ##
214 
216 
217 for info in sorted(set(parameterInfo)):
218  print "Parameter: ",info[0]
219  writeInfo(info)
220 
222 
223 outfile.close()
224 
225 
def parameterIntegerRangeList
Definition: xml2dox.py:37
def parameterDocumentationHeader
Definition: xml2dox.py:13
def parameterDocumentationFooter
Definition: xml2dox.py:19
def parameterStringToIntegral
Definition: xml2dox.py:92
def parameterString
Definition: xml2dox.py:122
def parameterFileName
Definition: xml2dox.py:67
def parameterEnhancedNumber
Definition: xml2dox.py:22
def writeInfo
Definition: xml2dox.py:133
def parameterAnyNumber
Definition: xml2dox.py:74