3 from datetime import date
11 from ovs.db import error
16 def textToNroff(s, font=r'\fR'):
20 if c != '-' or font == r'\fB':
31 raise error.Error("bad escape")
33 # Escape - \ " ' as needed by nroff.
34 s = re.sub('(-[0-9]|[-"\'\\\\])', escape, s)
39 def escapeNroffLiteral(s):
40 return r'\fB%s\fR' % textToNroff(s, r'\fB')
42 def inlineXmlToNroff(node, font):
43 if node.nodeType == node.TEXT_NODE:
44 return textToNroff(node.data, font)
45 elif node.nodeType == node.ELEMENT_NODE:
46 if node.tagName in ['code', 'em', 'option']:
48 for child in node.childNodes:
49 s += inlineXmlToNroff(child, r'\fB')
51 elif node.tagName == 'ref':
53 if node.hasAttribute('column'):
54 s += node.attributes['column'].nodeValue
55 if node.hasAttribute('key'):
56 s += ':' + node.attributes['key'].nodeValue
57 elif node.hasAttribute('table'):
58 s += node.attributes['table'].nodeValue
59 elif node.hasAttribute('group'):
60 s += node.attributes['group'].nodeValue
62 raise error.Error("'ref' lacks required attributes: %s" % node.attributes.keys())
64 elif node.tagName == 'var':
66 for child in node.childNodes:
67 s += inlineXmlToNroff(child, r'\fI')
70 raise error.Error("element <%s> unknown or invalid here" % node.tagName)
72 raise error.Error("unknown node %s in inline xml" % node)
74 def blockXmlToNroff(nodes, para='.PP'):
77 if node.nodeType == node.TEXT_NODE:
78 s += textToNroff(node.data)
80 elif node.nodeType == node.ELEMENT_NODE:
81 if node.tagName in ['ul', 'ol']:
86 for liNode in node.childNodes:
87 if (liNode.nodeType == node.ELEMENT_NODE
88 and liNode.tagName == 'li'):
90 if node.tagName == 'ul':
93 s += ".IP %d. .25in\n" % i
94 s += blockXmlToNroff(liNode.childNodes, ".IP")
95 elif (liNode.nodeType != node.TEXT_NODE
96 or not liNode.data.isspace()):
97 raise error.Error("<%s> element may only have <li> children" % node.tagName)
99 elif node.tagName == 'dl':
104 for liNode in node.childNodes:
105 if (liNode.nodeType == node.ELEMENT_NODE
106 and liNode.tagName == 'dt'):
112 elif (liNode.nodeType == node.ELEMENT_NODE
113 and liNode.tagName == 'dd'):
117 elif (liNode.nodeType != node.TEXT_NODE
118 or not liNode.data.isspace()):
119 raise error.Error("<dl> element may only have <dt> and <dd> children")
120 s += blockXmlToNroff(liNode.childNodes, ".IP")
122 elif node.tagName == 'p':
124 if not s.endswith("\n"):
127 s += blockXmlToNroff(node.childNodes, para)
128 elif node.tagName in ('h1', 'h2', 'h3'):
130 if not s.endswith("\n"):
132 nroffTag = {'h1': 'SH', 'h2': 'SS', 'h3': 'ST'}[node.tagName]
133 s += ".%s " % nroffTag
134 for child_node in node.childNodes:
135 s += inlineXmlToNroff(child_node, r'\fR')
138 s += inlineXmlToNroff(node, r'\fR')
140 raise error.Error("unknown node %s in block xml" % node)
141 if s != "" and not s.endswith('\n'):
145 def typeAndConstraintsToNroff(column):
146 type = column.type.toEnglish(escapeNroffLiteral)
147 constraints = column.type.constraintsToEnglish(escapeNroffLiteral,
150 type += ", " + constraints
152 type += " (must be unique within table)"
155 def columnGroupToNroff(table, groupXml):
158 for node in groupXml.childNodes:
159 if (node.nodeType == node.ELEMENT_NODE
160 and node.tagName in ('column', 'group')):
161 columnNodes += [node]
164 and not (node.nodeType == node.TEXT_NODE
165 and node.data.isspace())):
166 raise error.Error("text follows <column> or <group> inside <group>: %s" % node)
170 intro = blockXmlToNroff(introNodes)
172 for node in columnNodes:
173 if node.tagName == 'column':
174 name = node.attributes['name'].nodeValue
175 column = table.columns[name]
176 if node.hasAttribute('key'):
177 key = node.attributes['key'].nodeValue
178 if node.hasAttribute('type'):
179 type_string = node.attributes['type'].nodeValue
180 type_json = ovs.json.from_string(str(type_string))
181 if type(type_json) in (str, unicode):
182 raise error.Error("%s %s:%s has invalid 'type': %s"
183 % (table.name, name, key, type_json))
184 type_ = ovs.db.types.BaseType.from_json(type_json)
186 type_ = column.type.value
188 nameNroff = "%s : %s" % (name, key)
190 if column.type.value:
191 typeNroff = "optional %s" % column.type.value.toEnglish(
193 if (column.type.value.type == ovs.db.types.StringType and
194 type_.type == ovs.db.types.BooleanType):
195 # This is a little more explicit and helpful than
196 # "containing a boolean"
197 typeNroff += r", either \fBtrue\fR or \fBfalse\fR"
199 if type_.type != column.type.value.type:
200 type_english = type_.toEnglish()
201 if type_english[0] in 'aeiou':
202 typeNroff += ", containing an %s" % type_english
204 typeNroff += ", containing a %s" % type_english
206 type_.constraintsToEnglish(escapeNroffLiteral,
209 typeNroff += ", %s" % constraints
214 typeNroff = typeAndConstraintsToNroff(column)
215 if not column.mutable:
216 typeNroff = "immutable %s" % typeNroff
217 body += '.IP "\\fB%s\\fR: %s"\n' % (nameNroff, typeNroff)
218 body += blockXmlToNroff(node.childNodes, '.IP') + "\n"
219 summary += [('column', nameNroff, typeNroff)]
220 elif node.tagName == 'group':
221 title = node.attributes["title"].nodeValue
222 subSummary, subIntro, subBody = columnGroupToNroff(table, node)
223 summary += [('group', title, subSummary)]
224 body += '.ST "%s:"\n' % textToNroff(title)
225 body += subIntro + subBody
227 raise error.Error("unknown element %s in <table>" % node.tagName)
228 return summary, intro, body
230 def tableSummaryToNroff(summary, level=0):
232 for type, name, arg in summary:
234 s += ".TQ %.2fin\n\\fB%s\\fR\n%s\n" % (3 - level * .25, name, arg)
236 s += ".TQ .25in\n\\fI%s:\\fR\n.RS .25in\n" % name
237 s += tableSummaryToNroff(arg, level + 1)
241 def tableToNroff(schema, tableXml):
242 tableName = tableXml.attributes['name'].nodeValue
243 table = schema.tables[tableName]
248 summary, intro, body = columnGroupToNroff(table, tableXml)
250 s += '.SS "Summary:\n'
251 s += tableSummaryToNroff(summary)
252 s += '.SS "Details:\n'
256 def docsToNroff(schemaFile, xmlFile, erFile, title=None, version=None):
257 schema = ovs.db.schema.DbSchema.from_json(ovs.json.from_file(schemaFile))
258 doc = xml.dom.minidom.parse(xmlFile).documentElement
260 schemaDate = os.stat(schemaFile).st_mtime
261 xmlDate = os.stat(xmlFile).st_mtime
262 d = date.fromtimestamp(max(schemaDate, xmlDate))
270 # Putting '\" p as the first line tells "man" that the manpage
271 # needs to be preprocessed by "pic".
273 .TH "%s" 5 "%s" "Open vSwitch" "Open vSwitch Manual"
287 %s \- %s database schema
289 ''' % (title, version, textToNroff(schema.name), schema.name)
295 for dbNode in doc.childNodes:
296 if (dbNode.nodeType == dbNode.ELEMENT_NODE
297 and dbNode.tagName == "table"):
298 tableNodes += [dbNode]
300 name = dbNode.attributes['name'].nodeValue
301 if dbNode.hasAttribute("title"):
302 title = dbNode.attributes['title'].nodeValue
304 title = name + " configuration."
305 summary += [(name, title)]
307 introNodes += [dbNode]
309 s += blockXmlToNroff(introNodes) + "\n"
314 The following list summarizes the purpose of each of the tables in the
315 \fB%s\fR database. Each table is described in more detail on a later
320 for name, title in summary:
325 """ % (name, textToNroff(title))
329 .\\" check if in troff mode (TTY)
332 .SH "TABLE RELATIONSHIPS"
334 The following diagram shows the relationship among tables in the
335 database. Each node represents a table. Tables that are part of the
336 ``root set'' are shown with double borders. Each edge leads from the
337 table that contains it and points to the table that its value
338 represents. Edges are labeled with their column names, followed by a
339 constraint on the number of allowed values: \\fB?\\fR for zero or one,
340 \\fB*\\fR for zero or more, \\fB+\\fR for one or more. Thick lines
341 represent strong references; thin lines represent weak references.
344 erStream = open(erFile, "r")
345 for line in erStream:
350 for node in tableNodes:
351 s += tableToNroff(schema, node) + "\n"
356 %(argv0)s: ovsdb schema documentation generator
357 Prints documentation for an OVSDB schema as an nroff-formatted manpage.
358 usage: %(argv0)s [OPTIONS] SCHEMA XML
359 where SCHEMA is an OVSDB schema in JSON format
360 and XML is OVSDB documentation in XML format.
362 The following options are also available:
363 --er-diagram=DIAGRAM.PIC include E-R diagram from DIAGRAM.PIC
364 --title=TITLE use TITLE as title instead of schema name
365 --version=VERSION use VERSION to display on document footer
366 -h, --help display this help message\
367 """ % {'argv0': argv0}
370 if __name__ == "__main__":
373 options, args = getopt.gnu_getopt(sys.argv[1:], 'hV',
374 ['er-diagram=', 'title=',
376 except getopt.GetoptError, geo:
377 sys.stderr.write("%s: %s\n" % (argv0, geo.msg))
383 for key, value in options:
384 if key == '--er-diagram':
386 elif key == '--title':
388 elif key == '--version':
390 elif key in ['-h', '--help']:
396 sys.stderr.write("%s: exactly 2 non-option arguments required "
397 "(use --help for help)\n" % argv0)
400 # XXX we should warn about undocumented tables or columns
401 s = docsToNroff(args[0], args[1], er_diagram, title, version)
402 for line in s.split("\n"):
407 except error.Error, e:
408 sys.stderr.write("%s: %s\n" % (argv0, e.msg))