Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2020-09-29' into staging

QAPI patches patches for 2020-09-29

# gpg: Signature made Tue 29 Sep 2020 20:54:51 BST
# gpg:                using RSA key 354BC8B3D7EB2A6B68674E5F3870B400EB918653
# gpg:                issuer "armbru@redhat.com"
# gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" [full]
# gpg:                 aka "Markus Armbruster <armbru@pond.sub.org>" [full]
# Primary key fingerprint: 354B C8B3 D7EB 2A6B 6867  4E5F 3870 B400 EB91 8653

* remotes/armbru/tags/pull-qapi-2020-09-29: (29 commits)
  Remove texinfo dependency from docker and CI configs
  configure: Drop texinfo requirement
  Remove Texinfo related line from git.orderfile
  scripts/texi2pod: Delete unused script
  docs/devel/qapi-code-gen.txt: Update to new rST backend conventions
  scripts/qapi: Remove texinfo generation support
  tests/qapi-schema: Add test of the rST QAPI doc-comment output
  meson.build: Make manuals depend on source to Sphinx extensions
  meson.build: Move SPHINX_ARGS to top level meson.build file
  tests/qapi-schema: Convert doc-good.json to rST-style strong/emphasis
  qga/qapi-schema.json: Add some headings
  qapi: Use rST markup for literal blocks
  docs/interop: Convert qemu-qmp-ref to rST
  docs/interop: Convert qemu-ga-ref to rST
  docs/sphinx: Add new qapi-doc Sphinx extension
  qapi/machine.json: Escape a literal '*' in doc comment
  scripts/qapi/parser.py: improve doc comment indent handling
  scripts/qapi: Move doc-comment whitespace stripping to doc.py
  tests/qapi/doc-good.json: Prepare for qapi-doc Sphinx extension
  qapi/block.json: Add newline after "Example:" for block-latency-histogram-set
  ...

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

1 files changed, 72 insertions, 26 deletions

diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
index 9eede44..5fc67c9 100644
--- a/docs/devel/qapi-code-gen.txt
+++ b/docs/devel/qapi-code-gen.txt
@@ -824,23 +824,37 @@ See below for more on definition documentation.
 Free-form documentation may be used to provide additional text and
 structuring content.
 
+==== Headings and subheadings ====
 
-==== Documentation markup ====
+A free-form documentation comment containing a line which starts with
+some '=' symbols and then a space defines a section heading:
 
-Comment text starting with '=' is a section title:
+    ##
+    # = This is a top level heading
+    #
+    # This is a free-form comment which will go under the
+    # top level heading.
+    ##
 
-    # = Section title
+    ##
+    # == This is a second level heading
+    ##
 
-Double the '=' for a subsection title:
+A heading line must be the first line of the documentation
+comment block.
 
-    # == Subsection title
+Section headings must always be correctly nested, so you can only
+define a third-level heading inside a second-level heading, and so on.
 
-Both are only permitted in free-form documentation.
+==== Documentation markup ====
 
-'|' denotes examples:
+Documentation comments can use most rST markup.  In particular,
+a '::' literal block can be used for examples:
 
-    # | Text of the example, may span
-    # | multiple lines
+    # ::
+    #
+    #   Text of the example, may span
+    #   multiple lines
 
 '*' starts an itemized list:
 
@@ -856,34 +870,33 @@ A decimal number followed by '.' starts a numbered list:
     #    multiple lines
     # 2. Second item
 
-The actual number doesn't matter.  You could even use '*' instead of
-'2.' for the second item.
+The actual number doesn't matter.
 
-Lists can't be nested.  Blank lines are currently not supported within
-lists.
+Lists of either kind must be preceded and followed by a blank line.
+If a list item's text spans multiple lines, then the second and
+subsequent lines must be correctly indented to line up with the
+first character of the first line.
 
-Additional whitespace between the initial '#' and the comment text is
-permitted.
-
-*foo* and _foo_ are for strong and emphasis styles respectively (they
-do not work over multiple lines).  @foo is used to reference a name in
-the schema.
+The usual '**strong**', '*emphasised*' and '``literal``' markup should
+be used.  If you need a single literal '*' you will need to
+backslash-escape it.  As an extension beyond the usual rST syntax, you
+can also use '@foo' to reference a name in the schema; this is
+rendered the same way as '``foo``'.
 
 Example:
 
 ##
-# = Section
-# == Subsection
-#
-# Some text foo with *strong* and _emphasis_
+# Some text foo with **bold** and *emphasis*
 # 1. with a list
 # 2. like that
 #
 # And some code:
-# | $ echo foo
-# | -> do this
-# | <- get that
 #
+# ::
+#
+#   $ echo foo
+#   -> do this
+#   <- get that
 ##
 
 
@@ -901,6 +914,22 @@ commands and events), member (for structs and unions), branch (for
 alternates), or value (for enums), and finally optional tagged
 sections.
 
+Descriptions of arguments can span multiple lines.  The description
+text can start on the line following the '@argname:', in which case it
+must not be indented at all.  It can also start on the same line as
+the '@argname:'.  In this case if it spans multiple lines then second
+and subsequent lines must be indented to line up with the first
+character of the first line of the description:
+
+# @argone:
+# This is a two line description
+# in the first style.
+#
+# @argtwo: This is a two line description
+#          in the second style.
+
+The number of spaces between the ':' and the text is not significant.
+
 FIXME: the parser accepts these things in almost any order.
 FIXME: union branches should be described, too.
 
@@ -911,9 +940,26 @@ A tagged section starts with one of the following words:
 "Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:".
 The section ends with the start of a new section.
 
+The text of a section can start on a new line, in
+which case it must not be indented at all.  It can also start
+on the same line as the 'Note:', 'Returns:', etc tag.  In this
+case if it spans multiple lines then second and subsequent
+lines must be indented to match the first, in the same way as
+multiline argument descriptions.
+
 A 'Since: x.y.z' tagged section lists the release that introduced the
 definition.
 
+The text of a section can start on a new line, in
+which case it must not be indented at all.  It can also start
+on the same line as the 'Note:', 'Returns:', etc tag.  In this
+case if it spans multiple lines then second and subsequent
+lines must be indented to match the first.
+
+An 'Example' or 'Examples' section is automatically rendered
+entirely as literal fixed-width text.  In other sections,
+the text is formatted, and rST markup can be used.
+
 For example:
 
 ##