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 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             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 in ['ul', 'ol']:
  80                 if s != "":
  81                     s += "\n"
  82                 s += ".RS\n"
  83                 i = 0
  84                 for liNode in node.childNodes:
  85                     if (liNode.nodeType == node.ELEMENT_NODE
  86                         and liNode.tagName == 'li'):
  87                         i += 1
  88                         if node.tagName == 'ul':
  89                             s += ".IP \\bu\n"
  90                         else:
  91                             s += ".IP %d. .25in\n" % i
  92                         s += blockXmlToNroff(liNode.childNodes, ".IP")
  93                     elif (liNode.nodeType != node.TEXT_NODE
  94                           or not liNode.data.isspace()):
  95                         raise error.Error("<%s> element may only have <li> children" % node.tagName)
  96                 s += ".RE\n"
  97             elif node.tagName == 'dl':
  98                 if s != "":
  99                     s += "\n"
 100                 s += ".RS\n"
 101                 prev = "dd"
 102                 for liNode in node.childNodes:
 103                     if (liNode.nodeType == node.ELEMENT_NODE
 104                         and liNode.tagName == 'dt'):
 105                         if prev == 'dd':
 106                             s += '.TP\n'
 107                         else:
 108                             s += '.TQ\n'
 109                         prev = 'dt'
 110                     elif (liNode.nodeType == node.ELEMENT_NODE
 111                           and liNode.tagName == 'dd'):
 112                         if prev == 'dd':
 113                             s += '.IP\n'
 114                         prev = 'dd'
 115                     elif (liNode.nodeType != node.TEXT_NODE
 116                           or not liNode.data.isspace()):
 117                         raise error.Error("<dl> element may only have <dt> and <dd> children")
 118                     s += blockXmlToNroff(liNode.childNodes, ".IP")
 119                 s += ".RE\n"
 120             elif node.tagName == 'p':
 121                 if s != "":
 122                     if not s.endswith("\n"):
 123                         s += "\n"
 124                     s += para + "\n"
 125                 s += blockXmlToNroff(node.childNodes, para)
 126             else:
 127                 s += inlineXmlToNroff(node, r'\fR')
 128         else:
 129             raise error.Error("unknown node %s in block xml" % node)
 130     if s != "" and not s.endswith('\n'):
 131         s += '\n'
 132     return s
 133
 134 def typeAndConstraintsToNroff(column):
 135     type = column.type.toEnglish(escapeNroffLiteral)
 136     constraints = column.type.constraintsToEnglish(escapeNroffLiteral)
 137     if constraints:
 138         type += ", " + constraints
 139     return type
 140
 141 def columnToNroff(columnName, column, node):
 142     type = typeAndConstraintsToNroff(column)
 143     s = '.IP "\\fB%s\\fR: %s"\n' % (columnName, type)
 144     s += blockXmlToNroff(node.childNodes, '.IP') + "\n"
 145     return s
 146
 147 def columnGroupToNroff(table, groupXml):
 148     introNodes = []
 149     columnNodes = []
 150     for node in groupXml.childNodes:
 151         if (node.nodeType == node.ELEMENT_NODE
 152             and node.tagName in ('column', 'group')):
 153             columnNodes += [node]
 154         else:
 155             introNodes += [node]
 156
 157     summary = []
 158     intro = blockXmlToNroff(introNodes)
 159     body = ''
 160     for node in columnNodes:
 161         if node.tagName == 'column':
 162             columnName = node.attributes['name'].nodeValue
 163             column = table.columns[columnName]
 164             body += columnToNroff(columnName, column, node)
 165             summary += [('column', columnName, column)]
 166         elif node.tagName == 'group':
 167             title = node.attributes["title"].nodeValue
 168             subSummary, subIntro, subBody = columnGroupToNroff(table, node)
 169             summary += [('group', title, subSummary)]
 170             body += '.ST "%s:"\n' % textToNroff(title)
 171             body += subIntro + subBody
 172         else:
 173             raise error.Error("unknown element %s in <table>" % node.tagName)
 174     return summary, intro, body
 175
 176 def tableSummaryToNroff(summary, level=0):
 177     s = ""
 178     for type, name, arg in summary:
 179         if type == 'column':
 180
 181             s += "%s\\fB%s\\fR\tT{\n%s\nT}\n" % (
 182                 r'\ \ ' * level, name, typeAndConstraintsToNroff(arg))
 183         else:
 184             if s != "":
 185                 s += "_\n"
 186             s += """.T&
 187 li | s
 188 l | l.
 189 %s%s
 190 _
 191 """ % (r'\ \ ' * level, name)
 192             s += tableSummaryToNroff(arg, level + 1)
 193     return s
 194
 195 def tableToNroff(schema, tableXml):
 196     tableName = tableXml.attributes['name'].nodeValue
 197     table = schema.tables[tableName]
 198
 199     s = """.bp
 200 .SS "%s Table"
 201 """ % tableName
 202     summary, intro, body = columnGroupToNroff(table, tableXml)
 203     s += intro
 204
 205     s += r"""
 206 .sp
 207 .ce 1
 208 \fB%s\fR Table Columns:
 209 .TS
 210 center box;
 211 l | l.
 212 Column  Type
 213 =
 214 """ % tableName
 215     s += tableSummaryToNroff(summary)
 216     s += ".TE\n"
 217
 218     s += body
 219     return s
 220
 221 def docsToNroff(schemaFile, xmlFile, erFile, title=None):
 222     schema = ovs.db.schema.DbSchema.from_json(ovs.json.from_file(schemaFile))
 223     doc = xml.dom.minidom.parse(xmlFile).documentElement
 224
 225     schemaDate = os.stat(schemaFile).st_mtime
 226     xmlDate = os.stat(xmlFile).st_mtime
 227     d = date.fromtimestamp(max(schemaDate, xmlDate))
 228
 229     if title == None:
 230         title = schema.name
 231
 232     # Putting '\" pt as the first line tells "man" that the manpage
 233     # needs to be preprocessed by "pic" and "tbl".
 234     s = r''''\" pt
 235 .TH %s 5 "%s" "Open vSwitch" "Open vSwitch Manual"
 236 .\" -*- nroff -*-
 237 .de TQ
 238 .  br
 239 .  ns
 240 .  TP "\\$1"
 241 ..
 242 .de ST
 243 .  PP
 244 .  RS -0.15in
 245 .  I "\\$1"
 246 .  RE
 247 ..
 248 ''' % (title, d.strftime("%B %Y"))
 249
 250     s += '.SH "%s DATABASE"\n' % schema.name
 251
 252     tables = ""
 253     introNodes = []
 254     tableNodes = []
 255     summary = []
 256     for dbNode in doc.childNodes:
 257         if (dbNode.nodeType == dbNode.ELEMENT_NODE
 258             and dbNode.tagName == "table"):
 259             tableNodes += [dbNode]
 260
 261             name = dbNode.attributes['name'].nodeValue
 262             if dbNode.hasAttribute("title"):
 263                 title = dbNode.attributes['title'].nodeValue
 264             else:
 265                 title = name + " configuration."
 266             summary += [(name, title)]
 267         else:
 268             introNodes += [dbNode]
 269
 270     s += blockXmlToNroff(introNodes) + "\n"
 271     tableSummary = r"""
 272 .sp
 273 .ce 1
 274 \fB%s\fR Database Tables:
 275 .TS
 276 center box;
 277 l | l
 278 lb | l.
 279 Table   Purpose
 280 =
 281 """ % schema.name
 282     for name, title in summary:
 283         tableSummary += "%s\t%s\n" % (name, textToNroff(title))
 284     tableSummary += '.TE\n'
 285     s += tableSummary
 286
 287     if erFile:
 288         s += """
 289 .sp 1
 290 .SH "TABLE RELATIONSHIPS"
 291 .PP
 292 The following diagram shows the relationship among tables in the
 293 database.  Each node represents a table.  Each edge leads from the
 294 table that contains it and points to the table that its value
 295 represents.  Edges are labeled with their column names.
 296 .RS -1in
 297 """
 298         erStream = open(erFile, "r")
 299         for line in erStream:
 300             s += line + '\n'
 301         erStream.close()
 302         s += ".RE\n"
 303
 304     for node in tableNodes:
 305         s += tableToNroff(schema, node) + "\n"
 306     return s
 307
 308 def usage():
 309     print """\
 310 %(argv0)s: ovsdb schema documentation generator
 311 Prints documentation for an OVSDB schema as an nroff-formatted manpage.
 312 usage: %(argv0)s [OPTIONS] SCHEMA XML
 313 where SCHEMA is an OVSDB schema in JSON format
 314   and XML is OVSDB documentation in XML format.
 315
 316 The following options are also available:
 317   --er-diagram=DIAGRAM.PIC    include E-R diagram from DIAGRAM.PIC
 318   --title=TITLE               use TITLE as title instead of schema name
 319   -h, --help                  display this help message
 320   -V, --version               display version information\
 321 """ % {'argv0': argv0}
 322     sys.exit(0)
 323
 324 if __name__ == "__main__":
 325     try:
 326         try:
 327             options, args = getopt.gnu_getopt(sys.argv[1:], 'hV',
 328                                               ['er-diagram=', 'title=',
 329                                                'help', 'version'])
 330         except getopt.GetoptError, geo:
 331             sys.stderr.write("%s: %s\n" % (argv0, geo.msg))
 332             sys.exit(1)
 333
 334         er_diagram = None
 335         title = None
 336         for key, value in options:
 337             if key == '--er-diagram':
 338                 er_diagram = value
 339             elif key == '--title':
 340                 title = value
 341             elif key in ['-h', '--help']:
 342                 usage()
 343             elif key in ['-V', '--version']:
 344                 print "ovsdb-doc (Open vSwitch) @VERSION@"
 345             else:
 346                 sys.exit(0)
 347
 348         if len(args) != 2:
 349             sys.stderr.write("%s: exactly 2 non-option arguments required "
 350                              "(use --help for help)\n" % argv0)
 351             sys.exit(1)
 352
 353         # XXX we should warn about undocumented tables or columns
 354         s = docsToNroff(args[0], args[1], er_diagram)
 355         for line in s.split("\n"):
 356             line = line.strip()
 357             if len(line):
 358                 print line
 359
 360     except error.Error, e:
 361         sys.stderr.write("%s: %s\n" % (argv0, e.msg))
 362         sys.exit(1)
 363
 364 # Local variables:
 365 # mode: python
 366 # End: