3313b6124b
As the name suggests, the qapi2texi script converts JSON QAPI
description into a texi file suitable for different target
formats (info/man/txt/pdf/html...).
It parses the following kind of blocks:
Free-form:
##
# = Section
# == Subsection
#
# Some text foo with *emphasis*
# 1. with a list
# 2. like that
#
# And some code:
# | $ echo foo
# | -> do this
# | <- get that
#
##
Symbol description:
##
# @symbol:
#
# Symbol body ditto ergo sum. Foo bar
# baz ding.
#
# @param1: the frob to frobnicate
# @param2: #optional how hard to frobnicate
#
# Returns: the frobnicated frob.
# If frob isn't frobnicatable, GenericError.
#
# Since: version
# Notes: notes, comments can have
# - itemized list
# - like this
#
# Example:
#
# -> { "execute": "quit" }
# <- { "return": {} }
#
##
That's roughly following the following EBNF grammar:
api_comment = "##\n" comment "##\n"
comment = freeform_comment | symbol_comment
freeform_comment = { "# " text "\n" | "#\n" }
symbol_comment = "# @" name ":\n" { member | tag_section | freeform_comment }
member = "# @" name ':' [ text ] "\n" freeform_comment
tag_section = "# " ( "Returns:", "Since:", "Note:", "Notes:", "Example:", "Examples:" ) [ text ] "\n" freeform_comment
text = free text with markup
Note that the grammar is ambiguous: a line "# @foo:\n" can be parsed
both as freeform_comment and as symbol_comment. The actual parser
recognizes symbol_comment.
See docs/qapi-code-gen.txt for more details.
Deficiencies and limitations:
- the generated QMP documentation includes internal types
- union type support is lacking
- type information is lacking in generated documentation
- doc comment error message positions are imprecise, they point
to the beginning of the comment.
- a few minor issues, all marked TODO/FIXME in the code
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Message-Id: <20170113144135.5150-16-marcandre.lureau@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[test-qapi.py tweaked to avoid trailing empty lines in .out]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
72 lines
2.2 KiB
Python
72 lines
2.2 KiB
Python
#
|
|
# QAPI parser test harness
|
|
#
|
|
# Copyright (c) 2013 Red Hat Inc.
|
|
#
|
|
# Authors:
|
|
# Markus Armbruster <armbru@redhat.com>
|
|
#
|
|
# This work is licensed under the terms of the GNU GPL, version 2 or later.
|
|
# See the COPYING file in the top-level directory.
|
|
#
|
|
|
|
from qapi import *
|
|
from pprint import pprint
|
|
import os
|
|
import sys
|
|
|
|
|
|
class QAPISchemaTestVisitor(QAPISchemaVisitor):
|
|
def visit_enum_type(self, name, info, values, prefix):
|
|
print 'enum %s %s' % (name, values)
|
|
if prefix:
|
|
print ' prefix %s' % prefix
|
|
|
|
def visit_object_type(self, name, info, base, members, variants):
|
|
print 'object %s' % name
|
|
if base:
|
|
print ' base %s' % base.name
|
|
for m in members:
|
|
print ' member %s: %s optional=%s' % \
|
|
(m.name, m.type.name, m.optional)
|
|
self._print_variants(variants)
|
|
|
|
def visit_alternate_type(self, name, info, variants):
|
|
print 'alternate %s' % name
|
|
self._print_variants(variants)
|
|
|
|
def visit_command(self, name, info, arg_type, ret_type,
|
|
gen, success_response, boxed):
|
|
print 'command %s %s -> %s' % \
|
|
(name, arg_type and arg_type.name, ret_type and ret_type.name)
|
|
print ' gen=%s success_response=%s boxed=%s' % \
|
|
(gen, success_response, boxed)
|
|
|
|
def visit_event(self, name, info, arg_type, boxed):
|
|
print 'event %s %s' % (name, arg_type and arg_type.name)
|
|
print ' boxed=%s' % boxed
|
|
|
|
@staticmethod
|
|
def _print_variants(variants):
|
|
if variants:
|
|
print ' tag %s' % variants.tag_member.name
|
|
for v in variants.variants:
|
|
print ' case %s: %s' % (v.name, v.type.name)
|
|
|
|
schema = QAPISchema(sys.argv[1])
|
|
schema.visit(QAPISchemaTestVisitor())
|
|
|
|
for doc in schema.docs:
|
|
if doc.symbol:
|
|
print 'doc symbol=%s expr=%s' % \
|
|
(doc.symbol, doc.expr.items()[0])
|
|
else:
|
|
print 'doc freeform'
|
|
for arg, section in doc.args.iteritems():
|
|
print ' arg=%s\n%s' % (arg, section)
|
|
for section in doc.sections:
|
|
print ' section=%s\n%s' % (section.name, section)
|
|
body = str(doc.body)
|
|
if body:
|
|
print ' body=\n%s' % body
|