3 from datetime import date
11 from ovs.db import error
16 def textToNroff(s, font=r'\fR'):
31 raise error.Error("bad escape")
33 # Escape - \ " ' as needed by nroff.
34 s = re.sub('([-"\'\\\\])', 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 == 'code' or node.tagName == 'em':
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 elif node.hasAttribute('table'):
56 s += node.attributes['table'].nodeValue
57 elif node.hasAttribute('group'):
58 s += node.attributes['group'].nodeValue
60 raise error.Error("'ref' lacks column and table attributes")
62 elif node.tagName == 'var':
64 for child in node.childNodes:
65 s += inlineXmlToNroff(child, r'\fI')
68 raise error.Error("element <%s> unknown or invalid here" % node.tagName)
70 raise error.Error("unknown node %s in inline xml" % node)
72 def blockXmlToNroff(nodes, para='.PP'):
75 if node.nodeType == node.TEXT_NODE:
76 s += textToNroff(node.data)
78 elif node.nodeType == node.ELEMENT_NODE:
79 if node.tagName == 'ul':
83 for liNode in node.childNodes:
84 if (liNode.nodeType == node.ELEMENT_NODE
85 and liNode.tagName == 'li'):
86 s += ".IP \\(bu\n" + blockXmlToNroff(liNode.childNodes, ".IP")
87 elif (liNode.nodeType != node.TEXT_NODE
88 or not liNode.data.isspace()):
89 raise error.Error("<ul> element may only have <li> children")
91 elif node.tagName == 'dl':
96 for liNode in node.childNodes:
97 if (liNode.nodeType == node.ELEMENT_NODE
98 and liNode.tagName == 'dt'):
104 elif (liNode.nodeType == node.ELEMENT_NODE
105 and liNode.tagName == 'dd'):
109 elif (liNode.nodeType != node.TEXT_NODE
110 or not liNode.data.isspace()):
111 raise error.Error("<dl> element may only have <dt> and <dd> children")
112 s += blockXmlToNroff(liNode.childNodes, ".IP")
114 elif node.tagName == 'p':
116 if not s.endswith("\n"):
119 s += blockXmlToNroff(node.childNodes, para)
121 s += inlineXmlToNroff(node, r'\fR')
123 raise error.Error("unknown node %s in block xml" % node)
124 if s != "" and not s.endswith('\n'):
128 def typeAndConstraintsToNroff(column):
129 type = column.type.toEnglish(escapeNroffLiteral)
130 constraints = column.type.constraintsToEnglish(escapeNroffLiteral)
132 type += ", " + constraints
135 def columnToNroff(columnName, column, node):
136 type = typeAndConstraintsToNroff(column)
137 s = '.IP "\\fB%s\\fR: %s"\n' % (columnName, type)
138 s += blockXmlToNroff(node.childNodes, '.IP') + "\n"
141 def columnGroupToNroff(table, groupXml):
144 for node in groupXml.childNodes:
145 if (node.nodeType == node.ELEMENT_NODE
146 and node.tagName in ('column', 'group')):
147 columnNodes += [node]
152 intro = blockXmlToNroff(introNodes)
154 for node in columnNodes:
155 if node.tagName == 'column':
156 columnName = node.attributes['name'].nodeValue
157 column = table.columns[columnName]
158 body += columnToNroff(columnName, column, node)
159 summary += [('column', columnName, column)]
160 elif node.tagName == 'group':
161 title = node.attributes["title"].nodeValue
162 subSummary, subIntro, subBody = columnGroupToNroff(table, node)
163 summary += [('group', title, subSummary)]
164 body += '.ST "%s:"\n' % textToNroff(title)
165 body += subIntro + subBody
167 raise error.Error("unknown element %s in <table>" % node.tagName)
168 return summary, intro, body
170 def tableSummaryToNroff(summary, level=0):
172 for type, name, arg in summary:
175 s += "%s\\fB%s\\fR\tT{\n%s\nT}\n" % (
176 r'\ \ ' * level, name, typeAndConstraintsToNroff(arg))
185 """ % (r'\ \ ' * level, name)
186 s += tableSummaryToNroff(arg, level + 1)
189 def tableToNroff(schema, tableXml):
190 tableName = tableXml.attributes['name'].nodeValue
191 table = schema.tables[tableName]
196 summary, intro, body = columnGroupToNroff(table, tableXml)
202 \fB%s\fR Table Columns:
209 s += tableSummaryToNroff(summary)
215 def docsToNroff(schemaFile, xmlFile, erFile, title=None):
216 schema = ovs.db.schema.DbSchema.from_json(ovs.json.from_file(schemaFile))
217 doc = xml.dom.minidom.parse(xmlFile).documentElement
219 schemaDate = os.stat(schemaFile).st_mtime
220 xmlDate = os.stat(xmlFile).st_mtime
221 d = date.fromtimestamp(max(schemaDate, xmlDate))
226 # Putting '\" pt as the first line tells "man" that the manpage
227 # needs to be preprocessed by "pic" and "tbl".
229 .TH %s 5 "%s" "Open vSwitch" "Open vSwitch Manual"
242 ''' % (title, d.strftime("%B %Y"))
244 s += '.SH "%s DATABASE"\n' % schema.name
250 for dbNode in doc.childNodes:
251 if (dbNode.nodeType == dbNode.ELEMENT_NODE
252 and dbNode.tagName == "table"):
253 tableNodes += [dbNode]
255 name = dbNode.attributes['name'].nodeValue
256 if dbNode.hasAttribute("title"):
257 title = dbNode.attributes['title'].nodeValue
259 title = name + " configuration."
260 summary += [(name, title)]
262 introNodes += [dbNode]
264 s += blockXmlToNroff(introNodes) + "\n"
268 \fB%s\fR Database Tables:
276 for name, title in summary:
277 tableSummary += "%s\t%s\n" % (name, textToNroff(title))
278 tableSummary += '.TE\n'
284 .SH "TABLE RELATIONSHIPS"
286 The following diagram shows the relationship among tables in the
287 database. Each node represents a table. Each edge leads from the
288 table that contains it and points to the table that its value
289 represents. Edges are labeled with their column names.
292 erStream = open(erFile, "r")
293 for line in erStream:
298 for node in tableNodes:
299 s += tableToNroff(schema, node) + "\n"
304 %(argv0)s: ovsdb schema documentation generator
305 Prints documentation for an OVSDB schema as an nroff-formatted manpage.
306 usage: %(argv0)s [OPTIONS] SCHEMA XML
307 where SCHEMA is an OVSDB schema in JSON format
308 and XML is OVSDB documentation in XML format.
310 The following options are also available:
311 --er-diagram=DIAGRAM.PIC include E-R diagram from DIAGRAM.PIC
312 --title=TITLE use TITLE as title instead of schema name
313 -h, --help display this help message
314 -V, --version display version information\
315 """ % {'argv0': argv0}
318 if __name__ == "__main__":
321 options, args = getopt.gnu_getopt(sys.argv[1:], 'hV',
322 ['er-diagram=', 'title=',
324 except getopt.GetoptError, geo:
325 sys.stderr.write("%s: %s\n" % (argv0, geo.msg))
330 for key, value in options:
331 if key == '--er-diagram':
333 elif key == '--title':
335 elif key in ['-h', '--help']:
337 elif key in ['-V', '--version']:
338 print "ovsdb-doc (Open vSwitch) @VERSION@"
343 sys.stderr.write("%s: exactly 2 non-option arguments required "
344 "(use --help for help)\n" % argv0)
347 # XXX we should warn about undocumented tables or columns
348 s = docsToNroff(args[0], args[1], er_diagram)
349 for line in s.split("\n"):
354 except error.Error, e:
355 sys.stderr.write("%s: %s\n" % (argv0, e.msg))