[mirror_ovs.git] / ovsdb / ovsdb-doc.in

#! @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, font=r'\fR'):
    def escape(match):
        c = match.group(0)
        if c == '-':
            if font == r'\fB':
                return r'\-'
            else:
                return '-'
        if c == '\\':
            return r'\e'
        elif c == '"':
            return r'\(dq'
        elif c == "'":
            return r'\(cq'
        else:
            raise Error("bad escape")

    # Escape - \ " ' as needed by nroff.
    s = re.sub('([-"\'\\\\])', escape, s)
    if s.startswith('.'):
        s = '\\' + s
    return s

def escapeNroffLiteral(s):
    return r'\fB%s\fR' % textToNroff(s, r'\fB')

def inlineXmlToNroff(node, font):
    if node.nodeType == node.TEXT_NODE:
        return textToNroff(node.data, font)
    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:
Commit	Line	Data
89365653 BP	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	sys.path.insert(0, "@abs_top_srcdir@/ovsdb")
	11	import simplejson as json
	12
	13	from OVSDB import *
	14
	15	argv0 = sys.argv[0]
	16
fcbaf28c	17	def textToNroff(s, font=r'\fR'):
89365653 BP	18	def escape(match):
89365653 BP	19	c = match.group(0)
fcbaf28c BP	20	if c == '-':
	21	if font == r'\fB':
	22	return r'\-'
	23	else:
	24	return '-'
89365653 BP	25	if c == '\\':
	26	return r'\e'
	27	elif c == '"':
	28	return r'\(dq'
	29	elif c == "'":
	30	return r'\(cq'
	31	else:
	32	raise Error("bad escape")
	33
fcbaf28c BP	34	# Escape - \ " ' as needed by nroff.
fcbaf28c BP	35	s = re.sub('([-"\'\\\\])', escape, s)
89365653 BP	36	if s.startswith('.'):
	37	s = '\\' + s
	38	return s
	39
	40	def escapeNroffLiteral(s):
fcbaf28c	41	return r'\fB%s\fR' % textToNroff(s, r'\fB')
89365653 BP	42
	43	def inlineXmlToNroff(node, font):
	44	if node.nodeType == node.TEXT_NODE:
fcbaf28c	45	return textToNroff(node.data, font)
89365653 BP	46	elif node.nodeType == node.ELEMENT_NODE:
	47	if node.tagName == 'code' or node.tagName == 'em':
	48	s = r'\fB'
	49	for child in node.childNodes:
	50	s += inlineXmlToNroff(child, r'\fB')
	51	return s + font
	52	elif node.tagName == 'ref':
	53	s = r'\fB'
	54	if node.hasAttribute('column'):
	55	s += node.attributes['column'].nodeValue
	56	elif node.hasAttribute('table'):
	57	s += node.attributes['table'].nodeValue
	58	elif node.hasAttribute('group'):
	59	s += node.attributes['group'].nodeValue
	60	else:
	61	raise Error("'ref' lacks column and table attributes")
	62	return s + font
	63	elif node.tagName == 'var':
	64	s = r'\fI'
	65	for child in node.childNodes:
	66	s += inlineXmlToNroff(child, r'\fI')
	67	return s + font
	68	else:
	69	raise Error("element <%s> unknown or invalid here" % node.tagName)
	70	else:
	71	raise Error("unknown node %s in inline xml" % node)
	72
	73	def blockXmlToNroff(nodes, para='.PP'):
	74	s = ''
	75	for node in nodes:
	76	if node.nodeType == node.TEXT_NODE:
	77	s += textToNroff(node.data)
	78	s = s.lstrip()
	79	elif node.nodeType == node.ELEMENT_NODE:
	80	if node.tagName == 'ul':
	81	if s != "":
	82	s += "\n"
	83	s += ".RS\n"
	84	for liNode in node.childNodes:
	85	if (liNode.nodeType == node.ELEMENT_NODE
	86	and liNode.tagName == 'li'):
	87	s += ".IP \\(bu\n" + blockXmlToNroff(liNode.childNodes, ".IP")
	88	elif (liNode.nodeType != node.TEXT_NODE
	89	or not liNode.data.isspace()):
	90	raise Error("<ul> element may only have <li> children")
	91	s += ".RE\n"
	92	elif node.tagName == 'dl':
	93	if s != "":
	94	s += "\n"
	95	s += ".RS\n"
	96	prev = "dd"
	97	for liNode in node.childNodes:
	98	if (liNode.nodeType == node.ELEMENT_NODE
	99	and liNode.tagName == 'dt'):
	100	if prev == 'dd':
	101	s += '.TP\n'
	102	else:
	103	s += '.TQ\n'
	104	prev = 'dt'
	105	elif (liNode.nodeType == node.ELEMENT_NODE
	106	and liNode.tagName == 'dd'):
	107	if prev == 'dd':
	108	s += '.IP\n'
	109	prev = 'dd'
110	elif (liNode.nodeType != node.TEXT_NODE
111	or not liNode.data.isspace()):
112	raise Error("<dl> element may only have <dt> and <dd> children")
113	s += blockXmlToNroff(liNode.childNodes, ".IP")
114	s += ".RE\n"
115	elif node.tagName == 'p':
116	if s != "":
117	if not s.endswith("\n"):
118	s += "\n"
119	s += para + "\n"
120	s += blockXmlToNroff(node.childNodes, para)
121	else:
122	s += inlineXmlToNroff(node, r'\fR')
123	else:
124	raise Error("unknown node %s in block xml" % node)
125	if s != "" and not s.endswith('\n'):
126	s += '\n'
127	return s
128
129	def typeAndConstraintsToNroff(column):
130	type = column.type.toEnglish(escapeNroffLiteral)
131	constraints = column.type.constraintsToEnglish(escapeNroffLiteral)
132	if constraints:
133	type += ", " + constraints
134	return type
135
136	def columnToNroff(columnName, column, node):
137	type = typeAndConstraintsToNroff(column)
138	s = '.IP "\\fB%s\\fR: %s"\n' % (columnName, type)
139	s += blockXmlToNroff(node.childNodes, '.IP') + "\n"
140	return s
141
142	def columnGroupToNroff(table, groupXml):
143	introNodes = []
144	columnNodes = []
145	for node in groupXml.childNodes:
146	if (node.nodeType == node.ELEMENT_NODE
147	and node.tagName in ('column', 'group')):
148	columnNodes += [node]
149	else:
150	introNodes += [node]
151
152	summary = []
153	intro = blockXmlToNroff(introNodes)
154	body = ''
155	for node in columnNodes:
156	if node.tagName == 'column':
157	columnName = node.attributes['name'].nodeValue
158	column = table.columns[columnName]
159	body += columnToNroff(columnName, column, node)
160	summary += [('column', columnName, column)]
161	elif node.tagName == 'group':
162	title = node.attributes["title"].nodeValue
163	subSummary, subIntro, subBody = columnGroupToNroff(table, node)
164	summary += [('group', title, subSummary)]
165	body += '.ST "%s:"\n' % textToNroff(title)
166	body += subIntro + subBody
167	else:
168	raise Error("unknown element %s in <table>" % node.tagName)
169	return summary, intro, body
170
171	def tableSummaryToNroff(summary, level=0):
172	s = ""
173	for type, name, arg in summary:
174	if type == 'column':
175
176	s += "%s\\fB%s\\fR\tT{\n%s\nT}\n" % (
177	r'\ \ ' * level, name, typeAndConstraintsToNroff(arg))
178	else:
179	if s != "":
180	s += "_\n"
181	s += """.T&
182	li \| s
183	l \| l.
184	%s%s
185	_
186	""" % (r'\ \ ' * level, name)
187	s += tableSummaryToNroff(arg, level + 1)
188	return s
189
190	def tableToNroff(schema, tableXml):
191	tableName = tableXml.attributes['name'].nodeValue
192	table = schema.tables[tableName]
193
194	s = """.bp
195	.SS "%s Table"
196	""" % tableName
197	summary, intro, body = columnGroupToNroff(table, tableXml)
198	s += intro
199
200	s += r"""
201	.sp
202	.ce 1
203	\fB%s\fR Table Columns:
204	.TS
205	center box;
206	l \| l.
207	Column Type
208	=
209	""" % tableName
210	s += tableSummaryToNroff(summary)
211	s += ".TE\n"
212
213	s += body
214	return s
215
216	def docsToNroff(schemaFile, xmlFile, title=None):
217	schema = DbSchema.fromJson(json.load(open(schemaFile, "r")))
218	doc = xml.dom.minidom.parse(xmlFile).documentElement
219
220	schemaDate = os.stat(schemaFile).st_mtime
221	xmlDate = os.stat(xmlFile).st_mtime
222	d = date.fromtimestamp(max(schemaDate, xmlDate))
223
224	if title == None:
225	title = schema.name
226
227	s = r'''.TH %s 5 "%s" "Open vSwitch" "Open vSwitch Manual"
228	.\" -- nroff --
229	.de TQ
230	. br
231	. ns
232	. TP "\\$1"
233	..
234	.de ST
235	. PP
236	. RS -0.15in
237	. I "\\$1"
238	. RE
239	..
240	''' % (title, d.strftime("%B %Y"))
241
242	s += '.SH "%s DATABASE"\n' % schema.name
243
244	tables = ""
245	introNodes = []
246	tableNodes = []
247	summary = []
248	for dbNode in doc.childNodes:
249	if (dbNode.nodeType == dbNode.ELEMENT_NODE
250	and dbNode.tagName == "table"):
251	tableNodes += [dbNode]
252
253	name = dbNode.attributes['name'].nodeValue
254	if dbNode.hasAttribute("title"):
255	title = dbNode.attributes['title'].nodeValue
256	else:
257	title = name + " configuration."
258	summary += [(name, title)]
259	else:
260	introNodes += [dbNode]
261
262	s += blockXmlToNroff(introNodes) + "\n"
263	tableSummary = r"""
264	.sp
265	.ce 1
266	\fB%s\fR Database Tables:
267	.TS
268	center box;
269	l \| l
270	lb \| l.
271	Table Purpose
272	=
273	""" % schema.name
274	for name, title in summary:
275	tableSummary += "%s\t%s\n" % (name, textToNroff(title))
276	tableSummary += '.TE\n'
277	s += tableSummary
278	for node in tableNodes:
279	s += tableToNroff(schema, node) + "\n"
280	return s
281
282	def usage():
283	print """\
284	%(argv0)s: ovsdb schema documentation generator
285	Prints documentation for an OVSDB schema as an nroff-formatted manpage.
286	usage: %(argv0)s [OPTIONS] SCHEMA XML
287	where SCHEMA is an OVSDB schema in JSON format
288	and XML is OVSDB documentation in XML format.
289
290	The following options are also available:
291	--title=TITLE use TITLE as title instead of schema name
292	-h, --help display this help message
293	-V, --version display version information\
294	""" % {'argv0': argv0}
295	sys.exit(0)
296
297	if __name__ == "__main__":
298	try:
299	try:
300	options, args = getopt.gnu_getopt(sys.argv[1:], 'hV',
301	['title=', 'help', 'version'])
302	except getopt.GetoptError, geo:
303	sys.stderr.write("%s: %s\n" % (argv0, geo.msg))
304	sys.exit(1)
305
306	title = None
307	for key, value in options:
308	if key == '--title':
309	title = value
310	elif key in ['-h', '--help']:
311	usage()
312	elif key in ['-V', '--version']:
313	print "ovsdb-doc (Open vSwitch) @VERSION@"
314	else:
315	sys.exit(0)
316
317	if len(args) != 2:
318	sys.stderr.write("%s: exactly 2 non-option arguments required "
319	"(use --help for help)\n" % argv0)
320	sys.exit(1)
321
322	# XXX we should warn about undocumented tables or columns
323	s = docsToNroff(args[0], args[1])
324	for line in s.split("\n"):
325	line = line.strip()
326	if len(line):
327	print line
328
329	except Error, e:
330	sys.stderr.write("%s: %s\n" % (argv0, e.msg))
331	sys.exit(1)
332
333	# Local variables:
334	# mode: python
335	# End: