xemu/docs
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
..
specs vhost-user: Add MTU protocol feature and op 2017-01-10 07:02:53 +02:00
aio_notify_accept.promela AioContext: optimize clearing the EventNotifier 2015-07-22 12:41:40 +01:00
aio_notify_bug.promela AioContext: fix broken placement of event_notifier_test_and_clear 2015-07-22 12:41:40 +01:00
aio_notify.promela AioContext: fix broken ctx->dispatching optimization 2015-07-22 12:41:40 +01:00
atomics.txt atomic: base mb_read/mb_set on load-acquire and store-release 2016-10-24 15:27:15 +02:00
bitmaps.md docs: update bitmaps.md 2015-11-17 18:35:56 +08:00
blkdebug.txt blkdebug: Merge hand-rolled and qapi BlkdebugEvent enum 2015-12-17 08:21:27 +01:00
blkverify.txt blkverify: Add block driver for verifying I/O 2010-09-21 17:00:53 +02:00
block-replication.txt docs: block replication's description 2016-09-13 11:00:56 +01:00
bootindex.txt Typo, spelling and grammatical fixes 2013-04-12 14:33:20 +02:00
build-system.txt docs: Add text for tests/docker in build-system.txt 2016-06-01 17:27:35 +08:00
ccid.txt libcacard: improve documentation 2014-06-10 07:44:01 +02:00
COLO-FT.txt docs: fix COLO architecture diagram 2016-11-15 15:36:21 +08:00
colo-proxy.txt docs: Add documentation for COLO-proxy 2016-09-27 17:54:22 +08:00
generic-loader.txt docs/generic-loader: Update the document 2016-10-17 19:22:16 +01:00
ich9-ehci-uhci.cfg usb: update documentation 2011-07-08 11:25:56 +02:00
igd-assign.txt vfio/pci: Add IGD documentation 2016-05-26 11:12:05 -06:00
image-fuzzer.txt docs: List all image elements currently supported by the fuzzer 2014-09-22 11:39:35 +01:00
live-block-ops.txt docs: Document how to stream to an intermediate layer 2016-10-31 16:52:38 +01:00
memory-hotplug.txt docs: update documentation for memory hot unplug 2015-04-27 21:07:38 +02:00
memory.txt memory: Provide memory_region_init_rom() 2016-07-04 13:06:35 +01:00
migration.txt migration: convert post-copy to use QIOChannelBuffer 2016-05-26 11:31:34 +05:30
multi-thread-compression.txt docs/multi-thread-compression: Fix wrong command string 2016-06-07 18:19:24 +03:00
multiple-iothreads.txt iothread: release AioContext around aio_poll 2016-10-28 21:50:18 +08:00
multiseat.txt maint: remove / fix many doubled words 2015-09-11 10:21:38 +03:00
pci_expander_bridge.txt pxb: cleanup 2016-03-11 16:59:12 +02:00
pcie.txt doc/pcie: correct command line examples 2017-01-10 07:02:52 +02:00
q35-chipset.cfg q35: Add PCIe switch to example q35 configuration 2013-08-21 12:39:15 +03:00
qapi-code-gen.txt qapi: add qapi2texi script 2017-01-16 10:10:35 +01:00
qcow2-cache.txt docs: Specify that cache-clean-interval is only supported in Linux 2016-11-25 13:51:31 +01:00
qdev-device-use.txt docs: Fix qdev-device-use.txt typo in -chardev serial, path=COM<NUM> 2011-09-09 09:43:17 +01:00
qemu-ga-ref.texi docs: add master qapi texi files 2017-01-16 09:15:25 +01:00
qemu-qmp-ref.texi docs: add master qapi texi files 2017-01-16 09:15:25 +01:00
qemupciserial.inf Docs: Introduce multiport serial support in qemupciserial.inf. 2014-03-12 10:33:23 +01:00
qmp-intro.txt docs: Move files from docs/qmp/ to docs/ 2015-10-12 18:44:53 +02:00
qmp-spec.txt qapi: Update docs to match recent generator changes 2016-03-05 10:41:16 +01:00
rcu.txt docs/rcu.txt: Fix minor typo 2016-11-02 09:28:57 +01:00
rdma.txt rdma: Fix incorrect description in comments 2014-09-20 17:55:53 +04:00
replay.txt record/replay: add network support 2017-01-06 10:38:00 +08:00
spice-port-fqdn.txt docs: add spice-port-fqdn.txt 2012-12-17 14:01:41 +01:00
tcg-exclusive.promela cpus-common: lock-free fast path for cpu_exec_start/end 2016-09-27 11:57:30 +02:00
throttle.txt docs: Fix description of the leaky bucket algorithm in throttle.txt 2016-09-13 18:12:34 +03:00
tracing.txt docs/tracing.txt: Update documentation of default backend 2016-11-08 18:16:48 +00:00
usb2.txt usb: update docs for bus name change 2013-04-03 11:39:43 +02:00
usb-storage.txt usb: add storage hotplug documentation 2016-07-12 10:25:30 +02:00
virtio-balloon-stats.txt virtio-balloon: return empty data when no stats are available 2014-05-25 12:46:58 +03:00
virtio-migration.txt virtio: Update migration docs 2016-07-21 20:44:20 +03:00
vnc-ledstate-Pseudo-encoding.txt doc: document the Pseudo-encoding of LED state 2013-04-29 08:28:51 -05:00
win32-qemu-event.promela qemu-thread: add a fast path to the Win32 QemuEvent 2015-09-24 20:52:28 +02:00
writing-qmp-commands.txt docs: Belatedly update for move of QMP/* to docs/ 2016-10-07 19:22:11 +02:00
xbzrle.txt docs/xbzrle: correction 2016-10-13 17:23:53 +02:00
xen-save-devices-state.txt docs: Belatedly update for move of qmp-commands.txt 2016-10-07 19:22:11 +02:00