riscv
/
qemu
mirror of https://gitea.goldendeliverer.com/riscv/qemu.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

qapi2texi: Convert to QAPISchemaVisitor 

qapi2texi works with schema expression trees.  Such a tight coupling
to schema language syntax is not a good idea.  Convert it to the visitor
interface the other generators use.

No change to generated documentation.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <1489582656-31133-17-git-send-email-armbru@redhat.com>
pull/48/head
Markus Armbruster 9 years ago
parent
860e877861
commit
aa964b7fdc
1 changed files with 118 additions and 110 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 228
      scripts/qapi2texi.py

228
scripts/qapi2texi.py
View File

@ -123,31 +123,39 @@ def texi_format(doc):
return "\n".join(lines)
def texi_body(doc, only_documented=False):
"""
Format the body of a symbol documentation:
- main body
- table of arguments
- followed by "Returns/Notes/Since/Example" sections
"""
body = texi_format(str(doc.body)) + "\n"
args = ''
for name, section in doc.args.iteritems():
if not section.content and not only_documented:
continue # Undocumented TODO require doc and drop
desc = str(section)
opt = ''
if section.optional:
desc = re.sub(r'^ *#optional *\n?|\n? *#optional *$|#optional',
'', desc)
opt = ' (optional)'
args += "@item @code{'%s'}%s\n%s\n" % (name, opt, texi_format(desc))
if args:
body += "@table @asis\n"
body += args
body += "@end table\n"
def texi_body(doc):
"""Format the main documentation body"""
return texi_format(str(doc.body)) + '\n'
def texi_enum_value(value):
"""Format a table of members item for an enumeration value"""
return "@item @code{'%s'}\n" % value.name
def texi_member(member):
"""Format a table of members item for an object type member"""
return "@item @code{'%s'}%s\n" % (
member.name, ' (optional)' if member.optional else '')
def texi_members(doc, member_func, show_undocumented):
"""Format the table of members"""
items = ''
for section in doc.args.itervalues():
if not section.content and not show_undocumented:
continue # Undocumented TODO require doc and drop
desc = re.sub(r'^ *#optional *\n?|\n? *#optional *$|#optional',
'', str(section))
items += member_func(section.member) + texi_format(desc) + '\n'
if not items:
return ''
return '@table @asis\n' + items + '@end table\n'
def texi_sections(doc):
"""Format additional sections following arguments"""
body = ''
for section in doc.sections:
name, doc = (section.name, str(section))
func = texi_format
@ -159,94 +167,94 @@ def texi_body(doc, only_documented=False):
body += "\n\n@b{%s:}\n" % name
body += func(doc)
return body
def texi_alternate(expr, doc):
"""Format an alternate to texi"""
body = texi_body(doc)
return TYPE_FMT(type="Alternate",
name=doc.symbol,
body=body)
def texi_union(expr, doc):
"""Format a union to texi"""
discriminator = expr.get("discriminator")
if discriminator:
union = "Flat Union"
else:
union = "Simple Union"
body = texi_body(doc)
return TYPE_FMT(type=union,
name=doc.symbol,
body=body)
def texi_enum(expr, doc):
"""Format an enum to texi"""
body = texi_body(doc, True)
return TYPE_FMT(type="Enum",
name=doc.symbol,
body=body)
def texi_struct(expr, doc):
"""Format a struct to texi"""
body = texi_body(doc)
return TYPE_FMT(type="Struct",
name=doc.symbol,
body=body)
def texi_command(expr, doc):
"""Format a command to texi"""
body = texi_body(doc)
return MSG_FMT(type="Command",
name=doc.symbol,
body=body)
def texi_event(expr, doc):
"""Format an event to texi"""
body = texi_body(doc)
return MSG_FMT(type="Event",
name=doc.symbol,
body=body)
def texi_expr(expr, doc):
"""Format an expr to texi"""
(kind, _) = expr.items()[0]
fmt = {"command": texi_command,
"struct": texi_struct,
"enum": texi_enum,
"union": texi_union,
"alternate": texi_alternate,
"event": texi_event}[kind]
return fmt(expr, doc)
def texi(docs):
"""Convert QAPI schema expressions to texi documentation"""
res = []
for doc in docs:
expr = doc.expr
if not expr:
res.append(texi_body(doc))
continue
try:
doc = texi_expr(expr, doc)
res.append(doc)
except:
print >>sys.stderr, "error at @%s" % doc.info
raise
return '\n'.join(res)
def texi_entity(doc, member_func=texi_member, show_undocumented=False):
return (texi_body(doc)
+ texi_members(doc, member_func, show_undocumented)
+ texi_sections(doc))
class QAPISchemaGenDocVisitor(qapi.QAPISchemaVisitor):
def __init__(self):
self.out = None
self.cur_doc = None
def visit_begin(self, schema):
self.out = ''
def visit_enum_type(self, name, info, values, prefix):
doc = self.cur_doc
if self.out:
self.out += '\n'
self.out += TYPE_FMT(type='Enum',
name=doc.symbol,
body=texi_entity(doc,
member_func=texi_enum_value,
show_undocumented=True))
def visit_object_type(self, name, info, base, members, variants):
doc = self.cur_doc
if not variants:
typ = 'Struct'
elif variants._tag_name: # TODO unclean member access
typ = 'Flat Union'
else:
typ = 'Simple Union'
if self.out:
self.out += '\n'
self.out += TYPE_FMT(type=typ,
name=doc.symbol,
body=texi_entity(doc))
def visit_alternate_type(self, name, info, variants):
doc = self.cur_doc
if self.out:
self.out += '\n'
self.out += TYPE_FMT(type='Alternate',
name=doc.symbol,
body=texi_entity(doc))
def visit_command(self, name, info, arg_type, ret_type,
gen, success_response, boxed):
doc = self.cur_doc
if self.out:
self.out += '\n'
self.out += MSG_FMT(type='Command',
name=doc.symbol,
body=texi_entity(doc))
def visit_event(self, name, info, arg_type, boxed):
doc = self.cur_doc
if self.out:
self.out += '\n'
self.out += MSG_FMT(type='Event',
name=doc.symbol,
body=texi_entity(doc))
def symbol(self, doc, entity):
self.cur_doc = doc
entity.visit(self)
self.cur_doc = None
def freeform(self, doc):
assert not doc.args
if self.out:
self.out += '\n'
self.out += texi_body(doc) + texi_sections(doc)
def texi_schema(schema):
"""Convert QAPI schema documentation to Texinfo"""
gen = QAPISchemaGenDocVisitor()
gen.visit_begin(schema)
for doc in schema.docs:
if doc.symbol:
gen.symbol(doc, schema.lookup_entity(doc.symbol))
else:
gen.freeform(doc)
return gen.out
def main(argv):
@ -259,7 +267,7 @@ def main(argv):
if not qapi.doc_required:
print >>sys.stderr, ("%s: need pragma 'doc-required' "
"to generate documentation" % argv[0])
print texi(schema.docs)
print texi_schema(schema)
if __name__ == "__main__":

Write Preview
Loading…
Cancel
Save