mirrors/qemu
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
2d433236df
qemu/scripts/qapi2texi.py
Markus Armbruster 75b50196d9 qapi2texi: Use category "Object" for all object types 
At the protocol level, the distinction between struct, flat union and
simple union is meaningless, they are all JSON objects.  Document them
that way.

Example change (qemu-qmp-ref.txt):

- -- Simple Union: InputEvent
+ -- Object: InputEvent

      Input event union.

This also fixes the completely broken headings for flat and simple
unions in qemu-qmp-ref.7 and qemu-ga-ref.7, by sidestepping a bug in
texi2pod.pl.  For instance, it mistranslates "@deftp {Simple Union}
InputEvent" to "B<Union> (Simple)", but translates "@deftp Object
InputEvent" to "B<SocketAddress> (Object)".

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <1489582656-31133-30-git-send-email-armbru@redhat.com>
2017-03-16 07:13:03 +01:00

300 lines
8.8 KiB
Python
Executable File
Raw Blame History

#!/usr/bin/env python
# QAPI texi generator
#
# This work is licensed under the terms of the GNU LGPL, version 2+.
# See the COPYING file in the top-level directory.
"""This script produces the documentation of a qapi schema in texinfo format"""
import re
import sys
import qapi
MSG_FMT = """
@deftypefn {type} {{}} {name}
{body}
@end deftypefn
""".format
TYPE_FMT = """
@deftp {{{type}}} {name}
{body}
@end deftp
""".format
EXAMPLE_FMT = """@example
{code}
@end example
""".format
def subst_strong(doc):
"""Replaces *foo* by @strong{foo}"""
return re.sub(r'\*([^*\n]+)\*', r'@emph{\1}', doc)
def subst_emph(doc):
"""Replaces _foo_ by @emph{foo}"""
return re.sub(r'\b_([^_\n]+)_\b', r' @emph{\1} ', doc)
def subst_vars(doc):
"""Replaces @var by @code{var}"""
return re.sub(r'@([\w-]+)', r'@code{\1}', doc)
def subst_braces(doc):
"""Replaces {} with @{ @}"""
return doc.replace('{', '@{').replace('}', '@}')
def texi_example(doc):
"""Format @example"""
# TODO: Neglects to escape @ characters.
# We should probably escape them in subst_braces(), and rename the
# function to subst_special() or subs_texi_special(). If we do that, we
# need to delay it until after subst_vars() in texi_format().
doc = subst_braces(doc).strip('\n')
return EXAMPLE_FMT(code=doc)
def texi_format(doc):
"""
Format documentation
Lines starting with:
- |: generates an @example
- =: generates @section
- ==: generates @subsection
- 1. or 1): generates an @enumerate @item
- */-: generates an @itemize list
"""
lines = []
doc = subst_braces(doc)
doc = subst_vars(doc)
doc = subst_emph(doc)
doc = subst_strong(doc)
inlist = ''
lastempty = False
for line in doc.split('\n'):
empty = line == ''
# FIXME: Doing this in a single if / elif chain is
# problematic. For instance, a line without markup terminates
# a list if it follows a blank line (reaches the final elif),
# but a line with some *other* markup, such as a = title
# doesn't.
#
# Make sure to update section "Documentation markup" in
# docs/qapi-code-gen.txt when fixing this.
if line.startswith('| '):
line = EXAMPLE_FMT(code=line[2:])
elif line.startswith('= '):
line = '@section ' + line[2:]
elif line.startswith('== '):
line = '@subsection ' + line[3:]
elif re.match(r'^([0-9]*\.) ', line):
if not inlist:
lines.append('@enumerate')
inlist = 'enumerate'
line = line[line.find(' ')+1:]
lines.append('@item')
elif re.match(r'^[*-] ', line):
if not inlist:
lines.append('@itemize %s' % {'*': '@bullet',
'-': '@minus'}[line[0]])
inlist = 'itemize'
lines.append('@item')
line = line[2:]
elif lastempty and inlist:
lines.append('@end %s\n' % inlist)
inlist = ''
lastempty = empty
lines.append(line)
if inlist:
lines.append('@end %s\n' % inlist)
return '\n'.join(lines)
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, suffix=''):
"""Format a table of members item for an object type member"""
typ = member.type.doc_type()
return '@item @code{%s%s%s}%s%s\n' % (
member.name,
': ' if typ else '',
typ if typ else '',
' (optional)' if member.optional else '',
suffix)
def texi_members(doc, what, base, variants, member_func):
"""Format the table of members"""
items = ''
for section in doc.args.itervalues():
# TODO Drop fallbacks when undocumented members are outlawed
if section.content:
desc = texi_format(str(section))
elif (variants and variants.tag_member == section.member
and not section.member.type.doc_type()):
values = section.member.type.member_names()
desc = 'One of ' + ', '.join(['@t{"%s"}' % v for v in values])
else:
desc = 'Not documented'
items += member_func(section.member) + desc + '\n'
if base:
items += '@item The members of @code{%s}\n' % base.doc_type()
if variants:
for v in variants.variants:
when = ' when @code{%s} is @t{"%s"}' % (
variants.tag_member.name, v.name)
if v.type.is_implicit():
assert not v.type.base and not v.type.variants
for m in v.type.local_members:
items += member_func(m, when)
else:
items += '@item The members of @code{%s}%s\n' % (
v.type.doc_type(), when)
if not items:
return ''
return '\n@b{%s:}\n@table @asis\n%s@end table\n' % (what, items)
def texi_sections(doc):
"""Format additional sections following arguments"""
body = ''
for section in doc.sections:
name, doc = (section.name, str(section))
func = texi_format
if name.startswith('Example'):
func = texi_example
if name:
# prefer @b over @strong, so txt doesn't translate it to *Foo:*
body += '\n\n@b{%s:}\n' % name
body += func(doc)
return body
def texi_entity(doc, what, base=None, variants=None,
member_func=texi_member):
return (texi_body(doc)
+ texi_members(doc, what, base, variants, member_func)
+ 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, 'Values',
member_func=texi_enum_value))
def visit_object_type(self, name, info, base, members, variants):
doc = self.cur_doc
if base and base.is_implicit():
base = None
if self.out:
self.out += '\n'
self.out += TYPE_FMT(type='Object',
name=doc.symbol,
body=texi_entity(doc, 'Members', base, variants))
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, 'Members'))
def visit_command(self, name, info, arg_type, ret_type,
gen, success_response, boxed):
doc = self.cur_doc
if self.out:
self.out += '\n'
if boxed:
body = texi_body(doc)
body += '\n@b{Arguments:} the members of @code{%s}' % arg_type.name
body += texi_sections(doc)
else:
body = texi_entity(doc, 'Arguments')
self.out += MSG_FMT(type='Command',
name=doc.symbol,
body=body)
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, 'Arguments'))
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):
"""Takes schema argument, prints result to stdout"""
if len(argv) != 2:
print >>sys.stderr, "%s: need exactly 1 argument: SCHEMA" % argv[0]
sys.exit(1)
schema = qapi.QAPISchema(argv[1])
if not qapi.doc_required:
print >>sys.stderr, ("%s: need pragma 'doc-required' "
"to generate documentation" % argv[0])
print texi_schema(schema)
if __name__ == '__main__':
main(sys.argv)
Reference in New Issue View Git Blame Copy Permalink