diff options
Diffstat (limited to 'scripts/qapi/doc.py')
| -rw-r--r-- | scripts/qapi/doc.py | 274 |
1 files changed, 274 insertions, 0 deletions
diff --git a/scripts/qapi/doc.py b/scripts/qapi/doc.py new file mode 100644 index 0000000000..0ea68bf813 --- /dev/null +++ b/scripts/qapi/doc.py @@ -0,0 +1,274 @@ +#!/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""" + +from __future__ import print_function +import re +import qapi.common + +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'@strong{\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 + """ + ret = '' + 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/devel/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: + ret += '@enumerate\n' + inlist = 'enumerate' + ret += '@item\n' + line = line[line.find(' ')+1:] + elif re.match(r'^[*-] ', line): + if not inlist: + ret += '@itemize %s\n' % {'*': '@bullet', + '-': '@minus'}[line[0]] + inlist = 'itemize' + ret += '@item\n' + line = line[2:] + elif lastempty and inlist: + ret += '@end %s\n\n' % inlist + inlist = '' + + lastempty = empty + ret += line + '\n' + + if inlist: + ret += '@end %s\n\n' % inlist + return ret + + +def texi_body(doc): + """Format the main documentation body""" + return texi_format(doc.body.text) + + +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.values(): + # TODO Drop fallbacks when undocumented members are outlawed + if section.text: + desc = texi_format(section.text) + elif (variants and variants.tag_member == section.member + and not section.member.type.doc_type()): + values = section.member.type.member_names() + members_text = ', '.join(['@t{"%s"}' % v for v in values]) + desc = 'One of ' + members_text + '\n' + else: + desc = 'Not documented\n' + items += member_func(section.member) + desc + 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: + if section.name: + # prefer @b over @strong, so txt doesn't translate it to *Foo:* + body += '\n@b{%s:}\n' % section.name + if section.name and section.name.startswith('Example'): + body += texi_example(section.text) + else: + body += texi_format(section.text) + 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.common.QAPISchemaVisitor): + def __init__(self, prefix): + self._prefix = prefix + self._gen = qapi.common.QAPIGenDoc() + self.cur_doc = None + + def write(self, output_dir): + self._gen.write(output_dir, self._prefix + 'qapi-doc.texi') + + def visit_enum_type(self, name, info, values, prefix): + doc = self.cur_doc + self._gen.add(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 + self._gen.add(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 + self._gen.add(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 boxed: + body = texi_body(doc) + body += ('\n@b{Arguments:} the members of @code{%s}\n' + % arg_type.name) + body += texi_sections(doc) + else: + body = texi_entity(doc, 'Arguments') + self._gen.add(MSG_FMT(type='Command', + name=doc.symbol, + body=body)) + + def visit_event(self, name, info, arg_type, boxed): + doc = self.cur_doc + self._gen.add(MSG_FMT(type='Event', + name=doc.symbol, + body=texi_entity(doc, 'Arguments'))) + + def symbol(self, doc, entity): + if self._gen._body: + self._gen.add('\n') + self.cur_doc = doc + entity.visit(self) + self.cur_doc = None + + def freeform(self, doc): + assert not doc.args + if self._gen._body: + self._gen.add('\n') + self._gen.add(texi_body(doc) + texi_sections(doc)) + + +def gen_doc(schema, output_dir, prefix): + if not qapi.common.doc_required: + return + vis = QAPISchemaGenDocVisitor(prefix) + vis.visit_begin(schema) + for doc in schema.docs: + if doc.symbol: + vis.symbol(doc, schema.lookup_entity(doc.symbol)) + else: + vis.freeform(doc) + vis.write(output_dir) |