[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 18/29] qapi: Use rST markup for literal blocks
From: |
Markus Armbruster |
Subject: |
[PULL 18/29] qapi: Use rST markup for literal blocks |
Date: |
Tue, 29 Sep 2020 22:19:15 +0200 |
From: Peter Maydell <peter.maydell@linaro.org>
There are exactly two places in our json doc comments where we
use the markup accepted by the texi doc generator where a '|' in
the first line of a doc comment means the line should be emitted
as a literal block (fixed-width font, whitespace preserved).
Since we use this syntax so rarely, instead of making the rST
generator support it, instead just convert the two uses to
rST-format literal blocks, which are indented and introduced
with '::'.
(The rST generator doesn't complain about the old style syntax,
it just emits it with the '|' and with the whitespace not
preserved, which looks odd, but means we can safely leave this
change until after we've stopped generating texinfo.)
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-Id: <20200925162316.21205-11-peter.maydell@linaro.org>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/block-core.json | 16 +++++++++-------
qapi/qapi-schema.json | 6 ++++--
2 files changed, 13 insertions(+), 9 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index dd77a91174..86ed72ef9f 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -570,13 +570,15 @@
# For the example above, @bins may be something like [3, 1, 5, 2],
# and corresponding histogram looks like:
#
-# | 5| *
-# | 4| *
-# | 3| * *
-# | 2| * * *
-# | 1| * * * *
-# | +------------------
-# | 10 50 100
+# ::
+#
+# 5| *
+# 4| *
+# 3| * *
+# 2| * * *
+# 1| * * * *
+# +------------------
+# 10 50 100
#
# Since: 4.0
##
diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json
index 54c8ba6444..0c6ca5c000 100644
--- a/qapi/qapi-schema.json
+++ b/qapi/qapi-schema.json
@@ -21,8 +21,10 @@
#
# Example:
#
-# | -> data issued by the Client
-# | <- Server data response
+# ::
+#
+# -> data issued by the Client
+# <- Server data response
#
# Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for
# detailed information on the Server command and response formats.
--
2.26.2
- [PULL 27/29] Remove Texinfo related line from git.orderfile, (continued)
- [PULL 27/29] Remove Texinfo related line from git.orderfile, Markus Armbruster, 2020/09/29
- [PULL 20/29] tests/qapi-schema: Convert doc-good.json to rST-style strong/emphasis, Markus Armbruster, 2020/09/29
- [PULL 29/29] Remove texinfo dependency from docker and CI configs, Markus Armbruster, 2020/09/29
- [PULL 21/29] meson.build: Move SPHINX_ARGS to top level meson.build file, Markus Armbruster, 2020/09/29
- [PULL 16/29] docs/interop: Convert qemu-ga-ref to rST, Markus Armbruster, 2020/09/29
- [PULL 26/29] scripts/texi2pod: Delete unused script, Markus Armbruster, 2020/09/29
- [PULL 28/29] configure: Drop texinfo requirement, Markus Armbruster, 2020/09/29
- [PULL 23/29] tests/qapi-schema: Add test of the rST QAPI doc-comment output, Markus Armbruster, 2020/09/29
- [PULL 17/29] docs/interop: Convert qemu-qmp-ref to rST, Markus Armbruster, 2020/09/29
- [PULL 24/29] scripts/qapi: Remove texinfo generation support, Markus Armbruster, 2020/09/29
- [PULL 18/29] qapi: Use rST markup for literal blocks,
Markus Armbruster <=
- [PULL 13/29] scripts/qapi/parser.py: improve doc comment indent handling, Markus Armbruster, 2020/09/29
- [PULL 15/29] docs/sphinx: Add new qapi-doc Sphinx extension, Markus Armbruster, 2020/09/29
- [PULL 22/29] meson.build: Make manuals depend on source to Sphinx extensions, Markus Armbruster, 2020/09/29
- [PULL 12/29] scripts/qapi: Move doc-comment whitespace stripping to doc.py, Markus Armbruster, 2020/09/29
- [PULL 02/29] qapi: Correct balloon documentation, Markus Armbruster, 2020/09/29
- [PULL 14/29] qapi/machine.json: Escape a literal '*' in doc comment, Markus Armbruster, 2020/09/29
- [PULL 05/29] qapi: Restrict query-uuid command to machine code, Markus Armbruster, 2020/09/29
- [PULL 25/29] docs/devel/qapi-code-gen.txt: Update to new rST backend conventions, Markus Armbruster, 2020/09/29
- Re: [PULL 00/29] QAPI patches patches for 2020-09-29, Peter Maydell, 2020/09/30