xenserver: Add monitor-external-ids daemon
[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 == '-':
20             if font == r'\fB':
21                 return r'\-'
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('([-"\'\\\\])', 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 == 'code' or node.tagName == 'em':
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             elif node.hasAttribute('table'):
56                 s += node.attributes['table'].nodeValue
57             elif node.hasAttribute('group'):
58                 s += node.attributes['group'].nodeValue
59             else:
60                 raise error.Error("'ref' lacks column and table attributes")
61             return s + font
62         elif node.tagName == 'var':
63             s = r'\fI'
64             for child in node.childNodes:
65                 s += inlineXmlToNroff(child, r'\fI')
66             return s + font
67         else:
68             raise error.Error("element <%s> unknown or invalid here" % node.tagName)
69     else:
70         raise error.Error("unknown node %s in inline xml" % node)
71
72 def blockXmlToNroff(nodes, para='.PP'):
73     s = ''
74     for node in nodes:
75         if node.nodeType == node.TEXT_NODE:
76             s += textToNroff(node.data)
77             s = s.lstrip()
78         elif node.nodeType == node.ELEMENT_NODE:
79             if node.tagName == 'ul':
80                 if s != "":
81                     s += "\n"
82                 s += ".RS\n"
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")
90                 s += ".RE\n"
91             elif node.tagName == 'dl':
92                 if s != "":
93                     s += "\n"
94                 s += ".RS\n"
95                 prev = "dd"
96                 for liNode in node.childNodes:
97                     if (liNode.nodeType == node.ELEMENT_NODE
98                         and liNode.tagName == 'dt'):
99                         if prev == 'dd':
100                             s += '.TP\n'
101                         else:
102                             s += '.TQ\n'
103                         prev = 'dt'
104                     elif (liNode.nodeType == node.ELEMENT_NODE
105                           and liNode.tagName == 'dd'):
106                         if prev == 'dd':
107                             s += '.IP\n'
108                         prev = '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")
113                 s += ".RE\n"
114             elif node.tagName == 'p':
115                 if s != "":
116                     if not s.endswith("\n"):
117                         s += "\n"
118                     s += para + "\n"
119                 s += blockXmlToNroff(node.childNodes, para)
120             else:
121                 s += inlineXmlToNroff(node, r'\fR')
122         else:
123             raise error.Error("unknown node %s in block xml" % node)
124     if s != "" and not s.endswith('\n'):
125         s += '\n'
126     return s
127
128 def typeAndConstraintsToNroff(column):
129     type = column.type.toEnglish(escapeNroffLiteral)
130     constraints = column.type.constraintsToEnglish(escapeNroffLiteral)
131     if constraints:
132         type += ", " + constraints
133     return type
134
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"
139     return s
140
141 def columnGroupToNroff(table, groupXml):
142     introNodes = []
143     columnNodes = []
144     for node in groupXml.childNodes:
145         if (node.nodeType == node.ELEMENT_NODE
146             and node.tagName in ('column', 'group')):
147             columnNodes += [node]
148         else:
149             introNodes += [node]
150
151     summary = []
152     intro = blockXmlToNroff(introNodes)
153     body = ''
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
166         else:
167             raise error.Error("unknown element %s in <table>" % node.tagName)
168     return summary, intro, body
169
170 def tableSummaryToNroff(summary, level=0):
171     s = ""
172     for type, name, arg in summary:
173         if type == 'column':
174             
175             s += "%s\\fB%s\\fR\tT{\n%s\nT}\n" % (
176                 r'\ \ ' * level, name, typeAndConstraintsToNroff(arg))
177         else:
178             if s != "":
179                 s += "_\n"
180             s += """.T&
181 li | s
182 l | l.
183 %s%s
184 _
185 """ % (r'\ \ ' * level, name)
186             s += tableSummaryToNroff(arg, level + 1)
187     return s
188
189 def tableToNroff(schema, tableXml):
190     tableName = tableXml.attributes['name'].nodeValue
191     table = schema.tables[tableName]
192
193     s = """.bp
194 .SS "%s Table"
195 """ % tableName
196     summary, intro, body = columnGroupToNroff(table, tableXml)
197     s += intro
198
199     s += r"""
200 .sp
201 .ce 1
202 \fB%s\fR Table Columns:
203 .TS
204 center box;
205 l | l.
206 Column  Type
207 =
208 """ % tableName
209     s += tableSummaryToNroff(summary)
210     s += ".TE\n"
211
212     s += body
213     return s
214
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
218     
219     schemaDate = os.stat(schemaFile).st_mtime
220     xmlDate = os.stat(xmlFile).st_mtime
221     d = date.fromtimestamp(max(schemaDate, xmlDate))
222     
223     if title == None:
224         title = schema.name
225
226     # Putting '\" pt as the first line tells "man" that the manpage
227     # needs to be preprocessed by "pic" and "tbl".
228     s = r''''\" pt
229 .TH %s 5 "%s" "Open vSwitch" "Open vSwitch Manual"
230 .\" -*- nroff -*-
231 .de TQ
232 .  br
233 .  ns
234 .  TP "\\$1"
235 ..
236 .de ST
237 .  PP
238 .  RS -0.15in
239 .  I "\\$1"
240 .  RE
241 ..
242 ''' % (title, d.strftime("%B %Y"))
243
244     s += '.SH "%s DATABASE"\n' % schema.name
245
246     tables = ""
247     introNodes = []
248     tableNodes = []
249     summary = []
250     for dbNode in doc.childNodes:
251         if (dbNode.nodeType == dbNode.ELEMENT_NODE
252             and dbNode.tagName == "table"):
253             tableNodes += [dbNode]
254
255             name = dbNode.attributes['name'].nodeValue
256             if dbNode.hasAttribute("title"):
257                 title = dbNode.attributes['title'].nodeValue
258             else:
259                 title = name + " configuration."
260             summary += [(name, title)]
261         else:
262             introNodes += [dbNode]
263
264     s += blockXmlToNroff(introNodes) + "\n"
265     tableSummary = r"""
266 .sp
267 .ce 1
268 \fB%s\fR Database Tables:
269 .TS
270 center box;
271 l | l
272 lb | l.
273 Table   Purpose
274 =
275 """ % schema.name
276     for name, title in summary:
277         tableSummary += "%s\t%s\n" % (name, textToNroff(title))
278     tableSummary += '.TE\n'
279     s += tableSummary
280
281     if erFile:
282         s += """
283 .sp 1
284 .SH "TABLE RELATIONSHIPS"
285 .PP
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.
290 .RS -1in
291 """
292         erStream = open(erFile, "r")
293         for line in erStream:
294             s += line + '\n'
295         erStream.close()
296         s += ".RE\n"
297
298     for node in tableNodes:
299         s += tableToNroff(schema, node) + "\n"
300     return s
301
302 def usage():
303     print """\
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.
309
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}
316     sys.exit(0)
317
318 if __name__ == "__main__":
319     try:
320         try:
321             options, args = getopt.gnu_getopt(sys.argv[1:], 'hV',
322                                               ['er-diagram=', 'title=',
323                                                'help', 'version'])
324         except getopt.GetoptError, geo:
325             sys.stderr.write("%s: %s\n" % (argv0, geo.msg))
326             sys.exit(1)
327
328         er_diagram = None
329         title = None
330         for key, value in options:
331             if key == '--er-diagram':
332                 er_diagram = value
333             elif key == '--title':
334                 title = value
335             elif key in ['-h', '--help']:
336                 usage()
337             elif key in ['-V', '--version']:
338                 print "ovsdb-doc (Open vSwitch) @VERSION@"
339             else:
340                 sys.exit(0)
341             
342         if len(args) != 2:
343             sys.stderr.write("%s: exactly 2 non-option arguments required "
344                              "(use --help for help)\n" % argv0)
345             sys.exit(1)
346         
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"):
350             line = line.strip()
351             if len(line):
352                 print line
353             
354     except error.Error, e:
355         sys.stderr.write("%s: %s\n" % (argv0, e.msg))
356         sys.exit(1)
357
358 # Local variables:
359 # mode: python
360 # End: