qemu/scripts
Marc-André Lureau 3313b6124b qapi: add qapi2texi script
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>
2017-01-16 10:10:35 +01:00
..
coccinelle coccinelle: add a script to remove useless casts 2016-09-15 15:32:22 +03:00
kvm vmxcap: Add TSC scaling bit 2016-09-13 19:08:46 +02:00
modules scripts: Allow block module to not define BlockDriver 2016-10-07 14:14:06 +02:00
qemu-guest-agent qemu-ga: sample fsfreeze hooks 2013-01-08 16:38:12 -06:00
qemugdb scripts/gdb: Fix a python exception in mtree.py 2015-12-22 16:01:08 +08:00
qmp scripts: ensure monitor socket has SO_REUSEADDR set 2016-07-22 13:23:35 +05:30
tracetool trace: Fix 'char **' compilation error in simple backend 2016-10-27 19:24:15 +01:00
analyse-9p-simpletrace.py scripts/analyse-9p-simpletrace.py: Add symbolic names for 9p operations. 2011-12-21 12:37:23 +05:30
analyze-inclusions Move target-* CPU file into a target/ folder 2016-12-20 21:52:12 +01:00
analyze-migration.py migration: fix analyze-migration.py script 2015-11-04 13:40:13 +01:00
check-qerror.sh qerror: add check-qerror.sh to verify alphabetical order 2012-01-18 10:23:39 -02:00
checkpatch.pl checkpatch: allow spaces before parenthesis for 'coroutine_fn' 2016-11-02 09:28:56 +01:00
clean-header-guards.pl scripts: New clean-header-guards.pl 2016-07-12 16:19:16 +02:00
clean-includes scripts/clean-includes: added duplicate #include check 2016-10-28 18:17:23 +03:00
cleanup-trace-events.pl cleanup-trace-events.pl: Tighten search for trace event call 2014-09-26 09:34:38 +01:00
cocci-macro-file.h coccinelle: add g_assert_cmp* to macro file 2016-05-23 16:53:46 +02:00
coverity-model.c coverity: Model g_memdup() 2015-12-17 17:33:49 +01:00
create_config build-sys: define QEMU_VERSION_{MAJOR, MINOR, MICRO} 2016-09-19 17:32:21 +02:00
disas-objdump.pl disas-objdump: Pass --adjust-vma to objdump 2013-08-24 07:26:45 +02:00
dump-guest-memory.py exec: hide mr->ram_addr from qemu_get_ram_ptr users 2016-05-29 09:11:12 +02:00
extract-vsssdk-headers Add a script to extract VSS SDK headers on POSIX system 2013-09-09 14:17:56 -05:00
feature_to_c.sh scripts: Use $(..) instead of deprecated `..` 2016-06-07 18:19:23 +03:00
get_maintainer.pl get_maintainer.pl: fall back to git if only lists are found 2016-02-09 17:07:55 +01:00
gtester-cat test makefile overhaul 2012-03-30 08:14:11 -05:00
hxtool scripts/hxtool: fix undefined behavour of echo 2016-10-28 18:17:23 +03:00
make-release make-release: Record SeaBIOS version 2014-03-31 15:02:04 +01:00
make_device_config.sh scripts: Use $(..) instead of deprecated `..` 2016-06-07 18:19:23 +03:00
ordereddict.py qapi: Clean up qapi.py per pep8 2015-10-12 18:44:54 +02:00
qapi-commands.py qapi: rename QmpOutputVisitor to QObjectOutputVisitor 2016-10-25 16:25:54 +02:00
qapi-event.py qapi: rename QmpOutputVisitor to QObjectOutputVisitor 2016-10-25 16:25:54 +02:00
qapi-introspect.py qapi: Plumb in 'boxed' to qapi generator lower levels 2016-07-19 13:21:08 +02:00
qapi-types.py qapi: Add type.is_empty() helper 2016-07-19 13:21:08 +02:00
qapi-visit.py qapi: Drop useless gen_err_check() 2016-07-19 13:21:08 +02:00
qapi.py qapi: add qapi2texi script 2017-01-16 10:10:35 +01:00
qapi2texi.py qapi: add qapi2texi script 2017-01-16 10:10:35 +01:00
qemu-binfmt-conf.sh scripts: Use $(..) instead of deprecated `..` 2016-06-07 18:19:23 +03:00
qemu-gdb.py gdb command: qemu handlers 2015-10-29 17:59:27 +00:00
qemu.py iotest: fix python based IO tests 2016-07-26 18:28:40 +02:00
qtest.py iotest: fix python based IO tests 2016-07-26 18:28:40 +02:00
refresh-pxe-roms.sh roms: rewrite scripts/refresh-pxe-roms.sh 2013-09-30 09:44:35 +02:00
shaderinclude.pl opengl: add shader build infrastructure 2015-05-05 09:03:32 +02:00
show-fixed-bugs.sh scripts: Add a script to check for bug URLs in the git log 2016-09-22 20:20:53 +02:00
signrom.py linuxboot_dma: avoid guest ABI breakage on gcc vs. clang compilation 2016-08-09 22:57:36 +02:00
simpletrace.py trace: rename _read_events to read_events 2016-10-12 09:54:52 +02:00
switch-timer-api misc: Fix case Qemu -> QEMU 2014-02-15 16:10:25 +04:00
texi2pod.pl texi2pod: learn quotation, deftp and deftypefn 2017-01-16 09:15:25 +01:00
tracetool.py trace: fix generated code build break 2016-11-18 11:09:58 +00:00
update-linux-headers.sh scripts: Use $(..) instead of deprecated `..` 2016-06-07 18:19:23 +03:00
vmstate-static-checker.py vmstate-static-checker: fix size mismatch detection in unused fields 2016-06-17 18:24:33 +05:30