qapi: Fix bullet list markup in documentation

Peter Maydell's commit 100cc4fe0f08 explains:

    rST insists on a blank line before and after a bulleted list [...]
    Add some extra blank lines in the doc comments so they're
    acceptable rST input.

It missed one in qapi/trace.json.

Paolo Bonzini later added another instance in qapi/stats.json,
providing further, if unintended, evidence for his quip that rST is
the Perl of ASCII-based markups.

Both are parsed as ordinary paragraph, resulting in garbled output.

John Snow missed the need for a blank line when converting
docs/devel/qapi-code-gen.txt to rST.

Add the blank lines we need to get the bullet lists recognized as
such.

Kevin Wolf and Lukas Straub added two more, but indented.  Sphinx
recognizes them as (indented) bullet lists.  The indentation looks
slightly off.

Insert a blank line and delete the extra indentation.

Fixes: 100cc4fe0f0827f8da1a5c05f9c65e2aaa40e03d (qapi: Add blank lines before bulleted lists)
Fixes: 467ef823d83e (qmp: add filtering of statistics by target vCPU)
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Message-Id: <20230425064223.820979-10-armbru@redhat.com>
[Fix of docs/devel/qapi-code-gen.rst squashed, commit message adjusted]

diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index d81aac7a19f789d99df43ef4754b8c7e831c881d..ea0592034a39069e3091e657dc46a1383943e1c0 100644 (file)
--- a/docs/devel/qapi-code-gen.rst
+++ b/docs/devel/qapi-code-gen.rst
@@ -934,6 +934,7 @@ Example::
 
  ##
  # Some text foo with **bold** and *emphasis*
+ #
  # 1. with a list
  # 2. like that
  #

diff --git a/qapi/block-export.json b/qapi/block-export.json
index 4627bbc4e603853fe753c09a8125998081f79515..3be3de357f67c5da02354e0917161aa43200a38f 100644 (file)
--- a/qapi/block-export.json
+++ b/qapi/block-export.json
@@ -275,9 +275,10 @@
 # @deprecated: This command is deprecated. Use @block-export-del instead.
 #
 # Returns: error if
-#            - the server is not running
-#            - export is not found
-#            - mode is 'safe' and there are existing connections
+#
+#          - the server is not running
+#          - export is not found
+#          - mode is 'safe' and there are existing connections
 #
 # Since: 2.12
 ##

diff --git a/qapi/stats.json b/qapi/stats.json
index 1f5d3c59ab588d83ae90387e32d0d41d69db8fcf..f17495ee657473e0757c3f68da6f4d9184f0c080 100644 (file)
--- a/qapi/stats.json
+++ b/qapi/stats.json
@@ -107,6 +107,7 @@
 # The arguments to the query-stats command; specifies a target for which to
 # request statistics and optionally the required subset of information for
 # that target:
+#
 # - which vCPUs to request statistics for
 # - which providers to request statistics from
 # - which named values to return within each provider

diff --git a/qapi/trace.json b/qapi/trace.json
index 6c6982a58730df8001366b732926f231552240c5..f425d10764100edddc75efa7faf89cb46cae8717 100644 (file)
--- a/qapi/trace.json
+++ b/qapi/trace.json
@@ -87,6 +87,7 @@
 # @vcpu: The vCPU to act upon (all by default; since 2.7).
 #
 # An event's state is modified if:
+#
 # - its name matches the @name pattern, and
 # - if @vcpu is given, the event has the "vcpu" property.
 #

diff --git a/qapi/yank.json b/qapi/yank.json
index 167a775594ec626d27b264f9cbb966fe45c07325..1639744ada61aaae1b342af05a0e1ec359d26aac 100644 (file)
--- a/qapi/yank.json
+++ b/qapi/yank.json
@@ -50,16 +50,17 @@
 # hanging QEMU.
 #
 # Currently implemented yank instances:
-#  - nbd block device:
-#    Yanking it will shut down the connection to the nbd server without
-#    attempting to reconnect.
-#  - socket chardev:
-#    Yanking it will shut down the connected socket.
-#  - migration:
-#    Yanking it will shut down all migration connections. Unlike
-#    @migrate_cancel, it will not notify the migration process, so migration
-#    will go into @failed state, instead of @cancelled state. @yank should be
-#    used to recover from hangs.
+#
+# - nbd block device:
+#   Yanking it will shut down the connection to the nbd server without
+#   attempting to reconnect.
+# - socket chardev:
+#   Yanking it will shut down the connected socket.
+# - migration:
+#   Yanking it will shut down all migration connections. Unlike
+#   @migrate_cancel, it will not notify the migration process, so migration
+#   will go into @failed state, instead of @cancelled state. @yank should be
+#   used to recover from hangs.
 #
 # Since: 6.0
 ##