ofproto-dpif: Fix typo in comment.
[sliver-openvswitch.git] / ovsdb / ovsdb-doc.in
1 #! @PYTHON@
2
3 from datetime import date
4 import getopt
5 import os
6 import re
7 import sys
8 import xml.dom.minidom
9
10 import ovs.json
11 from ovs.db import error
12 import ovs.db.schema
13
14 argv0 = sys.argv[0]
15
16 def textToNroff(s, font=r'\fR'):
17     def escape(match):
18         c = match.group(0)
19         if c.startswith('-'):
20             if c != '-' or font == r'\fB':
21                 return '\\' + c
22             else:
23                 return '-'
24         if c == '\\':
25             return r'\e'
26         elif c == '"':
27             return r'\(dq'
28         elif c == "'":
29             return r'\(cq'
30         else:
31             raise error.Error("bad escape")
32
33     # Escape - \ " ' as needed by nroff.
34     s = re.sub('(-[0-9]|[-"\'\\\\])', escape, s)
35     if s.startswith('.'):
36         s = '\\' + s
37     return s
38
39 def escapeNroffLiteral(s):
40     return r'\fB%s\fR' % textToNroff(s, r'\fB')
41
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']:
47             s = r'\fB'
48             for child in node.childNodes:
49                 s += inlineXmlToNroff(child, r'\fB')
50             return s + font
51         elif node.tagName == 'ref':
52             s = r'\fB'
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
61             else:
62                 raise error.Error("'ref' lacks required attributes: %s" % node.attributes.keys())
63             return s + font
64         elif node.tagName == 'var':
65             s = r'\fI'
66             for child in node.childNodes:
67                 s += inlineXmlToNroff(child, r'\fI')
68             return s + font
69         else:
70             raise error.Error("element <%s> unknown or invalid here" % node.tagName)
71     else:
72         raise error.Error("unknown node %s in inline xml" % node)
73
74 def blockXmlToNroff(nodes, para='.PP'):
75     s = ''
76     for node in nodes:
77         if node.nodeType == node.TEXT_NODE:
78             s += textToNroff(node.data)
79             s = s.lstrip()
80         elif node.nodeType == node.ELEMENT_NODE:
81             if node.tagName in ['ul', 'ol']:
82                 if s != "":
83                     s += "\n"
84                 s += ".RS\n"
85                 i = 0
86                 for liNode in node.childNodes:
87                     if (liNode.nodeType == node.ELEMENT_NODE
88                         and liNode.tagName == 'li'):
89                         i += 1
90                         if node.tagName == 'ul':
91                             s += ".IP \\(bu\n"
92                         else:
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)
98                 s += ".RE\n"
99             elif node.tagName == 'dl':
100                 if s != "":
101                     s += "\n"
102                 s += ".RS\n"
103                 prev = "dd"
104                 for liNode in node.childNodes:
105                     if (liNode.nodeType == node.ELEMENT_NODE
106                         and liNode.tagName == 'dt'):
107                         if prev == 'dd':
108                             s += '.TP\n'
109                         else:
110                             s += '.TQ\n'
111                         prev = 'dt'
112                     elif (liNode.nodeType == node.ELEMENT_NODE
113                           and liNode.tagName == 'dd'):
114                         if prev == 'dd':
115                             s += '.IP\n'
116                         prev = '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")
121                 s += ".RE\n"
122             elif node.tagName == 'p':
123                 if s != "":
124                     if not s.endswith("\n"):
125                         s += "\n"
126                     s += para + "\n"
127                 s += blockXmlToNroff(node.childNodes, para)
128             elif node.tagName in ('h1', 'h2', 'h3'):
129                 if s != "":
130                     if not s.endswith("\n"):
131                         s += "\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')
136                 s += "\n"
137             else:
138                 s += inlineXmlToNroff(node, r'\fR')
139         else:
140             raise error.Error("unknown node %s in block xml" % node)
141     if s != "" and not s.endswith('\n'):
142         s += '\n'
143     return s
144
145 def typeAndConstraintsToNroff(column):
146     type = column.type.toEnglish(escapeNroffLiteral)
147     constraints = column.type.constraintsToEnglish(escapeNroffLiteral,
148                                                    textToNroff)
149     if constraints:
150         type += ", " + constraints
151     if column.unique:
152         type += " (must be unique within table)"
153     return type
154
155 def columnGroupToNroff(table, groupXml):
156     introNodes = []
157     columnNodes = []
158     for node in groupXml.childNodes:
159         if (node.nodeType == node.ELEMENT_NODE
160             and node.tagName in ('column', 'group')):
161             columnNodes += [node]
162         else:
163             if (columnNodes
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)
167             introNodes += [node]
168
169     summary = []
170     intro = blockXmlToNroff(introNodes)
171     body = ''
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)
185                 else:
186                     type_ = column.type.value
187
188                 nameNroff = "%s : %s" % (name, key)
189
190                 if column.type.value:
191                     typeNroff = "optional %s" % column.type.value.toEnglish(
192                         escapeNroffLiteral)
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"
198                     else:
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
203                             else:
204                                 typeNroff += ", containing a %s" % type_english
205                         constraints = (
206                             type_.constraintsToEnglish(escapeNroffLiteral,
207                                                        textToNroff))
208                         if constraints:
209                             typeNroff += ", %s" % constraints
210                 else:
211                     typeNroff = "none"
212             else:
213                 nameNroff = name
214                 typeNroff = typeAndConstraintsToNroff(column)
215             body += '.IP "\\fB%s\\fR: %s"\n' % (nameNroff, typeNroff)
216             body += blockXmlToNroff(node.childNodes, '.IP') + "\n"
217             summary += [('column', nameNroff, typeNroff)]
218         elif node.tagName == 'group':
219             title = node.attributes["title"].nodeValue
220             subSummary, subIntro, subBody = columnGroupToNroff(table, node)
221             summary += [('group', title, subSummary)]
222             body += '.ST "%s:"\n' % textToNroff(title)
223             body += subIntro + subBody
224         else:
225             raise error.Error("unknown element %s in <table>" % node.tagName)
226     return summary, intro, body
227
228 def tableSummaryToNroff(summary, level=0):
229     s = ""
230     for type, name, arg in summary:
231         if type == 'column':
232             s += ".TQ %.2fin\n\\fB%s\\fR\n%s\n" % (3 - level * .25, name, arg)
233         else:
234             s += ".TQ .25in\n\\fI%s:\\fR\n.RS .25in\n" % name
235             s += tableSummaryToNroff(arg, level + 1)
236             s += ".RE\n"
237     return s
238
239 def tableToNroff(schema, tableXml):
240     tableName = tableXml.attributes['name'].nodeValue
241     table = schema.tables[tableName]
242
243     s = """.bp
244 .SH "%s TABLE"
245 """ % tableName
246     summary, intro, body = columnGroupToNroff(table, tableXml)
247     s += intro
248     s += '.SS "Summary:\n'
249     s += tableSummaryToNroff(summary)
250     s += '.SS "Details:\n'
251     s += body
252     return s
253
254 def docsToNroff(schemaFile, xmlFile, erFile, title=None):
255     schema = ovs.db.schema.DbSchema.from_json(ovs.json.from_file(schemaFile))
256     doc = xml.dom.minidom.parse(xmlFile).documentElement
257
258     schemaDate = os.stat(schemaFile).st_mtime
259     xmlDate = os.stat(xmlFile).st_mtime
260     d = date.fromtimestamp(max(schemaDate, xmlDate))
261
262     if title == None:
263         title = schema.name
264
265     # Putting '\" p as the first line tells "man" that the manpage
266     # needs to be preprocessed by "pic".
267     s = r''''\" p
268 .TH %s 5 "%s" "Open vSwitch" "Open vSwitch Manual"
269 .\" -*- nroff -*-
270 .de TQ
271 .  br
272 .  ns
273 .  TP "\\$1"
274 ..
275 .de ST
276 .  PP
277 .  RS -0.15in
278 .  I "\\$1"
279 .  RE
280 ..
281 .SH NAME
282 %s \- %s database schema
283 ''' % (title, d.strftime("%B %Y"), textToNroff(title), schema.name)
284
285     tables = ""
286     introNodes = []
287     tableNodes = []
288     summary = []
289     for dbNode in doc.childNodes:
290         if (dbNode.nodeType == dbNode.ELEMENT_NODE
291             and dbNode.tagName == "table"):
292             tableNodes += [dbNode]
293
294             name = dbNode.attributes['name'].nodeValue
295             if dbNode.hasAttribute("title"):
296                 title = dbNode.attributes['title'].nodeValue
297             else:
298                 title = name + " configuration."
299             summary += [(name, title)]
300         else:
301             introNodes += [dbNode]
302
303     s += blockXmlToNroff(introNodes) + "\n"
304
305     s += r"""
306 .SH "TABLE SUMMARY"
307 .PP
308 The following list summarizes the purpose of each of the tables in the
309 \fB%s\fR database.  Each table is described in more detail on a later
310 page.
311 .IP "Table" 1in
312 Purpose
313 """ % schema.name
314     for name, title in summary:
315         s += r"""
316 .TQ 1in
317 \fB%s\fR
318 %s
319 """ % (name, textToNroff(title))
320
321     if erFile:
322         s += """
323 .\\" check if in troff mode (TTY)
324 .if t \{
325 .bp
326 .SH "TABLE RELATIONSHIPS"
327 .PP
328 The following diagram shows the relationship among tables in the
329 database.  Each node represents a table.  Tables that are part of the
330 ``root set'' are shown with double borders.  Each edge leads from the
331 table that contains it and points to the table that its value
332 represents.  Edges are labeled with their column names, followed by a
333 constraint on the number of allowed values: \\fB?\\fR for zero or one,
334 \\fB*\\fR for zero or more, \\fB+\\fR for one or more.  Thick lines
335 represent strong references; thin lines represent weak references.
336 .RS -1in
337 """
338         erStream = open(erFile, "r")
339         for line in erStream:
340             s += line + '\n'
341         erStream.close()
342         s += ".RE\\}\n"
343
344     for node in tableNodes:
345         s += tableToNroff(schema, node) + "\n"
346     return s
347
348 def usage():
349     print """\
350 %(argv0)s: ovsdb schema documentation generator
351 Prints documentation for an OVSDB schema as an nroff-formatted manpage.
352 usage: %(argv0)s [OPTIONS] SCHEMA XML
353 where SCHEMA is an OVSDB schema in JSON format
354   and XML is OVSDB documentation in XML format.
355
356 The following options are also available:
357   --er-diagram=DIAGRAM.PIC    include E-R diagram from DIAGRAM.PIC
358   --title=TITLE               use TITLE as title instead of schema name
359   -h, --help                  display this help message
360   -V, --version               display version information\
361 """ % {'argv0': argv0}
362     sys.exit(0)
363
364 if __name__ == "__main__":
365     try:
366         try:
367             options, args = getopt.gnu_getopt(sys.argv[1:], 'hV',
368                                               ['er-diagram=', 'title=',
369                                                'help', 'version'])
370         except getopt.GetoptError, geo:
371             sys.stderr.write("%s: %s\n" % (argv0, geo.msg))
372             sys.exit(1)
373
374         er_diagram = None
375         title = None
376         for key, value in options:
377             if key == '--er-diagram':
378                 er_diagram = value
379             elif key == '--title':
380                 title = value
381             elif key in ['-h', '--help']:
382                 usage()
383             elif key in ['-V', '--version']:
384                 print "ovsdb-doc (Open vSwitch) @VERSION@"
385             else:
386                 sys.exit(0)
387
388         if len(args) != 2:
389             sys.stderr.write("%s: exactly 2 non-option arguments required "
390                              "(use --help for help)\n" % argv0)
391             sys.exit(1)
392
393         # XXX we should warn about undocumented tables or columns
394         s = docsToNroff(args[0], args[1], er_diagram)
395         for line in s.split("\n"):
396             line = line.strip()
397             if len(line):
398                 print line
399
400     except error.Error, e:
401         sys.stderr.write("%s: %s\n" % (argv0, e.msg))
402         sys.exit(1)
403
404 # Local variables:
405 # mode: python
406 # End: