Add documentation for the vswitch database schema.

We can do better than this (I already have some comments) but this is
still much better than what we had.

Author: blp

ovsdb/OVSDB.py

@@ -82,22 +82,19 @@ EXTRA_DIST += \
 	ovsdb/simplejson/tests/test_separators.py		\
 	ovsdb/simplejson/tests/test_unicode.py			\
 	ovsdb/simplejson/tool.py
-noinst_SCRIPTS += ovsdb/ovsdb-idlc
+noinst_SCRIPTS += ovsdb/ovsdb-idlc 
 EXTRA_DIST += \
 	ovsdb/ovsdb-idlc.in \
 	ovsdb/ovsdb-idlc.1
 DISTCLEANFILES += ovsdb/ovsdb-idlc
-SUFFIXES += .ovsidl .txt
+SUFFIXES += .ovsidl
 OVSDB_IDLC = $(PYTHON) $(srcdir)/ovsdb/ovsdb-idlc.in
 .ovsidl.c:
 	$(OVSDB_IDLC) c-idl-source $< > $@.tmp
 	mv $@.tmp $@
 .ovsidl.h:
 	$(OVSDB_IDLC) c-idl-header $< > $@.tmp
 	mv $@.tmp $@
-.ovsidl.txt:
-	$(OVSDB_IDLC) doc $< | fmt -s > $@.tmp
-	mv $@.tmp $@
 
 EXTRA_DIST += $(OVSIDL_BUILT)
 BUILT_SOURCES += $(OVSIDL_BUILT)
@@ -111,3 +108,9 @@ BUILT_SOURCES += $(OVSIDL_BUILT)
 # assignments before any targets, so it doesn't seem to be a problem,
 # at least for now.
 $(OVSIDL_BUILT): ovsdb/ovsdb-idlc.in
+
+# ovsdb-doc
+EXTRA_DIST += ovsdb/ovsdb-doc.in
+noinst_SCRIPTS += ovsdb/ovsdb-doc
+DISTCLEANFILES += ovsdb/ovsdb-doc
+OVSDB_DOC = $(PYTHON) $(srcdir)/ovsdb/ovsdb-doc.in

ovsdb/automake.mk

@@ -0,0 +1,329 @@
+#! @PYTHON@
+
+from datetime import date
+import getopt
+import os
+import re
+import sys
+import xml.dom.minidom
+
+sys.path.insert(0, "@abs_top_srcdir@/ovsdb")
+import simplejson as json
+
+from OVSDB import *
+
+argv0 = sys.argv[0]
+
+def textToNroff(s):
+    def escape(match):
+        c = match.group(0)
+        if c == '\\':
+            return r'\e'
+        elif c == '"':
+            return r'\(dq'
+        elif c == "'":
+            return r'\(cq'
+        else:
+            raise Error("bad escape")
+
+    s = re.sub('([\\\\"\'])', escape, s)
+    if s.startswith('.'):
+        s = '\\' + s
+    return s
+
+def escapeNroffLiteral(s):
+    return r'\fB%s\fR' % textToNroff(s)
+
+def inlineXmlToNroff(node, font):
+    if node.nodeType == node.TEXT_NODE:
+        return textToNroff(node.data)
+    elif node.nodeType == node.ELEMENT_NODE:
+        if node.tagName == 'code' or node.tagName == 'em':
+            s = r'\fB'
+            for child in node.childNodes:
+                s += inlineXmlToNroff(child, r'\fB')
+            return s + font
+        elif node.tagName == 'ref':
+            s = r'\fB'
+            if node.hasAttribute('column'):
+                s += node.attributes['column'].nodeValue
+            elif node.hasAttribute('table'):
+                s += node.attributes['table'].nodeValue
+            elif node.hasAttribute('group'):
+                s += node.attributes['group'].nodeValue
+            else:
+                raise Error("'ref' lacks column and table attributes")
+            return s + font
+        elif node.tagName == 'var':
+            s = r'\fI'
+            for child in node.childNodes:
+                s += inlineXmlToNroff(child, r'\fI')
+            return s + font
+        else:
+            raise Error("element <%s> unknown or invalid here" % node.tagName)
+    else:
+        raise Error("unknown node %s in inline xml" % node)
+
+def blockXmlToNroff(nodes, para='.PP'):
+    s = ''
+    for node in nodes:
+        if node.nodeType == node.TEXT_NODE:
+            s += textToNroff(node.data)
+            s = s.lstrip()
+        elif node.nodeType == node.ELEMENT_NODE:
+            if node.tagName == 'ul':
+                if s != "":
+                    s += "\n"
+                s += ".RS\n"
+                for liNode in node.childNodes:
+                    if (liNode.nodeType == node.ELEMENT_NODE
+                        and liNode.tagName == 'li'):
+                        s += ".IP \\(bu\n" + blockXmlToNroff(liNode.childNodes, ".IP")
+                    elif (liNode.nodeType != node.TEXT_NODE
+                          or not liNode.data.isspace()):
+                        raise Error("<ul> element may only have <li> children")
+                s += ".RE\n"
+            elif node.tagName == 'dl':
+                if s != "":
+                    s += "\n"
+                s += ".RS\n"
+                prev = "dd"
+                for liNode in node.childNodes:
+                    if (liNode.nodeType == node.ELEMENT_NODE
+                        and liNode.tagName == 'dt'):
+                        if prev == 'dd':
+                            s += '.TP\n'
+                        else:
+                            s += '.TQ\n'
+                        prev = 'dt'
+                    elif (liNode.nodeType == node.ELEMENT_NODE
+                          and liNode.tagName == 'dd'):
+                        if prev == 'dd':
+                            s += '.IP\n'
+                        prev = 'dd'
+                    elif (liNode.nodeType != node.TEXT_NODE
+                          or not liNode.data.isspace()):
+                        raise Error("<dl> element may only have <dt> and <dd> children")
+                    s += blockXmlToNroff(liNode.childNodes, ".IP")
+                s += ".RE\n"
+            elif node.tagName == 'p':
+                if s != "":
+                    if not s.endswith("\n"):
+                        s += "\n"
+                    s += para + "\n"
+                s += blockXmlToNroff(node.childNodes, para)
+            else:
+                s += inlineXmlToNroff(node, r'\fR')
+        else:
+            raise Error("unknown node %s in block xml" % node)
+    if s != "" and not s.endswith('\n'):
+        s += '\n'
+    return s
+
+def typeAndConstraintsToNroff(column):
+    type = column.type.toEnglish(escapeNroffLiteral)
+    constraints = column.type.constraintsToEnglish(escapeNroffLiteral)
+    if constraints:
+        type += ", " + constraints
+    return type
+
+def columnToNroff(columnName, column, node):
+    type = typeAndConstraintsToNroff(column)
+    s = '.IP "\\fB%s\\fR: %s"\n' % (columnName, type)
+    s += blockXmlToNroff(node.childNodes, '.IP') + "\n"
+    return s
+
+def columnGroupToNroff(table, groupXml):
+    introNodes = []
+    columnNodes = []
+    for node in groupXml.childNodes:
+        if (node.nodeType == node.ELEMENT_NODE
+            and node.tagName in ('column', 'group')):
+            columnNodes += [node]
+        else:
+            introNodes += [node]
+
+    summary = []
+    intro = blockXmlToNroff(introNodes)
+    body = ''
+    for node in columnNodes:
+        if node.tagName == 'column':
+            columnName = node.attributes['name'].nodeValue
+            column = table.columns[columnName]
+            body += columnToNroff(columnName, column, node)
+            summary += [('column', columnName, column)]
+        elif node.tagName == 'group':
+            title = node.attributes["title"].nodeValue
+            subSummary, subIntro, subBody = columnGroupToNroff(table, node)
+            summary += [('group', title, subSummary)]
+            body += '.ST "%s:"\n' % textToNroff(title)
+            body += subIntro + subBody
+        else:
+            raise Error("unknown element %s in <table>" % node.tagName)
+    return summary, intro, body
+
+def tableSummaryToNroff(summary, level=0):
+    s = ""
+    for type, name, arg in summary:
+        if type == 'column':
+            
+            s += "%s\\fB%s\\fR\tT{\n%s\nT}\n" % (
+                r'\ \ ' * level, name, typeAndConstraintsToNroff(arg))
+        else:
+            if s != "":
+                s += "_\n"
+            s += """.T&
+li | s
+l | l.
+%s%s
+_
+""" % (r'\ \ ' * level, name)
+            s += tableSummaryToNroff(arg, level + 1)
+    return s
+
+def tableToNroff(schema, tableXml):
+    tableName = tableXml.attributes['name'].nodeValue
+    table = schema.tables[tableName]
+
+    s = """.bp
+.SS "%s Table"
+""" % tableName
+    summary, intro, body = columnGroupToNroff(table, tableXml)
+    s += intro
+
+    s += r"""
+.sp
+.ce 1
+\fB%s\fR Table Columns:
+.TS
+center box;
+l | l.
+Column	Type
+=
+""" % tableName
+    s += tableSummaryToNroff(summary)
+    s += ".TE\n"
+
+    s += body
+    return s
+
+def docsToNroff(schemaFile, xmlFile, title=None):
+    schema = DbSchema.fromJson(json.load(open(schemaFile, "r")))
+    doc = xml.dom.minidom.parse(xmlFile).documentElement
+
+    schemaDate = os.stat(schemaFile).st_mtime
+    xmlDate = os.stat(xmlFile).st_mtime
+    d = date.fromtimestamp(max(schemaDate, xmlDate))
+    
+    if title == None:
+        title = schema.name
+
+    s = r'''.TH %s 5 "%s" "Open vSwitch" "Open vSwitch Manual"
+.\" -*- nroff -*-
+.de TQ
+.  br
+.  ns
+.  TP "\\$1"
+..
+.de ST
+.  PP
+.  RS -0.15in
+.  I "\\$1"
+.  RE
+..
+''' % (title, d.strftime("%B %Y"))
+
+    s += '.SH "%s DATABASE"\n' % schema.name
+
+    tables = ""
+    introNodes = []
+    tableNodes = []
+    summary = []
+    for dbNode in doc.childNodes:
+        if (dbNode.nodeType == dbNode.ELEMENT_NODE
+            and dbNode.tagName == "table"):
+            tableNodes += [dbNode]
+
+            name = dbNode.attributes['name'].nodeValue
+            if dbNode.hasAttribute("title"):
+                title = dbNode.attributes['title'].nodeValue
+            else:
+                title = name + " configuration."
+            summary += [(name, title)]
+        else:
+            introNodes += [dbNode]
+
+    s += blockXmlToNroff(introNodes) + "\n"
+    tableSummary = r"""
+.sp
+.ce 1
+\fB%s\fR Database Tables:
+.TS
+center box;
+l | l
+lb | l.
+Table	Purpose
+=
+""" % schema.name
+    for name, title in summary:
+        tableSummary += "%s\t%s\n" % (name, textToNroff(title))
+    tableSummary += '.TE\n'
+    s += tableSummary
+    for node in tableNodes:
+        s += tableToNroff(schema, node) + "\n"
+    return s
+
+def usage():
+    print """\
+%(argv0)s: ovsdb schema documentation generator
+Prints documentation for an OVSDB schema as an nroff-formatted manpage.
+usage: %(argv0)s [OPTIONS] SCHEMA XML
+where SCHEMA is an OVSDB schema in JSON format
+  and XML is OVSDB documentation in XML format.
+
+The following options are also available:
+  --title=TITLE               use TITLE as title instead of schema name
+  -h, --help                  display this help message
+  -V, --version               display version information\
+""" % {'argv0': argv0}
+    sys.exit(0)
+
+if __name__ == "__main__":
+    try:
+        try:
+            options, args = getopt.gnu_getopt(sys.argv[1:], 'hV',
+                                              ['title=', 'help', 'version'])
+        except getopt.GetoptError, geo:
+            sys.stderr.write("%s: %s\n" % (argv0, geo.msg))
+            sys.exit(1)
+
+        title = None
+        for key, value in options:
+            if key == '--title':
+                title = value
+            elif key in ['-h', '--help']:
+                usage()
+            elif key in ['-V', '--version']:
+                print "ovsdb-doc (Open vSwitch) @VERSION@"
+            else:
+                sys.exit(0)
+            
+        if len(args) != 2:
+            sys.stderr.write("%s: exactly 2 non-option arguments required "
+                             "(use --help for help)\n" % argv0)
+            sys.exit(1)
+        
+        # XXX we should warn about undocumented tables or columns
+        s = docsToNroff(args[0], args[1])
+        for line in s.split("\n"):
+            line = line.strip()
+            if len(line):
+                print line
+            
+    except Error, e:
+        sys.stderr.write("%s: %s\n" % (argv0, e.msg))
+        sys.exit(1)
+
+# Local variables:
+# mode: python
+# End: