From 23d017ca84c82ebae6988b73f0675a0a4f539bca Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 4 Apr 2025 14:14:03 +0200 Subject: [PATCH 01/11] docs/devel/qapi-code-gen: Tidy up whitespace Consistently use two spaces to separate sentences. Put "::" on a line of its own when it's preceded by whitespace. Signed-off-by: Markus Armbruster Message-ID: <20250404121413.1743790-2-armbru@redhat.com> Reviewed-by: Eric Blake --- docs/devel/qapi-code-gen.rst | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index f9cfe8721f..ad517349fc 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -763,8 +763,8 @@ Names beginning with ``x-`` used to signify "experimental". This convention has been replaced by special feature "unstable". Pragmas ``command-name-exceptions`` and ``member-name-exceptions`` let -you violate naming rules. Use for new code is strongly discouraged. See -`Pragma directives`_ for details. +you violate naming rules. Use for new code is strongly discouraged. +See `Pragma directives`_ for details. Downstream extensions @@ -1013,7 +1013,7 @@ like this:: document the success and the error response, respectively. "Errors" sections should be formatted as an rST list, each entry -detailing a relevant error condition. For example:: +detailing a relevant error condition. For example:: # Errors: # - If @device does not exist, DeviceNotFound @@ -1026,13 +1026,13 @@ definition. QMP). In other sections, the text is formatted, and rST markup can be used. -QMP Examples can be added by using the ``.. qmp-example::`` -directive. In its simplest form, this can be used to contain a single -QMP code block which accepts standard JSON syntax with additional server +QMP Examples can be added by using the ``.. qmp-example::`` directive. +In its simplest form, this can be used to contain a single QMP code +block which accepts standard JSON syntax with additional server directionality indicators (``->`` and ``<-``), and elisions (``...``). Optionally, a plaintext title may be provided by using the ``:title:`` -directive option. If the title is omitted, the example title will +directive option. If the title is omitted, the example title will default to "Example:". A simple QMP example:: @@ -1043,10 +1043,10 @@ A simple QMP example:: # -> { "execute": "query-block" } # <- { ... } -More complex or multi-step examples where exposition is needed before or -between QMP code blocks can be created by using the ``:annotated:`` -directive option. When using this option, nested QMP code blocks must be -entered explicitly with rST's ``::`` syntax. +More complex or multi-step examples where exposition is needed before +or between QMP code blocks can be created by using the ``:annotated:`` +directive option. When using this option, nested QMP code blocks must +be entered explicitly with rST's ``::`` syntax. Highlighting in non-QMP languages can be accomplished by using the ``.. code-block:: lang`` directive, and non-highlighted text can be @@ -1466,7 +1466,9 @@ As an example, we'll use the following schema, which describes a single complex user-defined type, along with command which takes a list of that type as a parameter, and returns a single element of that type. The user is responsible for writing the implementation of -qmp_my_command(); everything else is produced by the generator. :: +qmp_my_command(); everything else is produced by the generator. + +:: $ cat example-schema.json { 'struct': 'UserDefOne', From 2f0bcc65a8e7d2e6ff28884e596355d70b03acc6 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 4 Apr 2025 14:14:04 +0200 Subject: [PATCH 02/11] qapi/rocker: Tidy up query-rocker-of-dpa-flows example The command can return any number of RockerOfDpaFlow objects. The example shows it returning exactly two, with the second object's members elided. Tweak it so it elides elements after the first instead. Signed-off-by: Markus Armbruster Message-ID: <20250404121413.1743790-3-armbru@redhat.com> Reviewed-by: Eric Blake [Commit message typo fixed] --- qapi/rocker.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/qapi/rocker.json b/qapi/rocker.json index 51aa5b4930..0c7ef1f77c 100644 --- a/qapi/rocker.json +++ b/qapi/rocker.json @@ -254,7 +254,7 @@ # "action": {"goto-tbl": 10}, # "mask": {"in-pport": 4294901760} # }, -# {...}, +# ... # ]} ## { 'command': 'query-rocker-of-dpa-flows', From ae75c37e50f37b224bef4c6191da6a577afedf1e Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 4 Apr 2025 14:14:05 +0200 Subject: [PATCH 03/11] docs/interop: Delete "QEMU Guest Agent Protocol Reference" TOC The "QEMU Guest Agent Protocol Reference" starts with the following table of contents: Contents * QEMU Guest Agent Protocol Reference * QEMU guest agent protocol commands and structs This is useless. Delete the entire TOC. Signed-off-by: Markus Armbruster Message-ID: <20250404121413.1743790-4-armbru@redhat.com> Reviewed-by: Eric Blake --- docs/interop/qemu-ga-ref.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/interop/qemu-ga-ref.rst b/docs/interop/qemu-ga-ref.rst index 19b5c7a549..25f6e24b03 100644 --- a/docs/interop/qemu-ga-ref.rst +++ b/docs/interop/qemu-ga-ref.rst @@ -1,9 +1,6 @@ QEMU Guest Agent Protocol Reference =================================== -.. contents:: - :depth: 3 - .. qapi-doc:: qga/qapi-schema.json :transmogrify: :namespace: QGA From 0d4c7ea0f8b8655f55cb33f6a75243a2dcb64447 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 4 Apr 2025 14:14:06 +0200 Subject: [PATCH 04/11] docs/interop: Sanitize QMP reference manuals TOC The "QEMU QMP Reference Manual" and the "QEMU Storage Daemon QMP Reference Manual" start with a table of contents that looks like this: Contents * Title of the manual * Title of first first-level section * Title of its first second-level section * Title of its second second-level section ... * Title of second first-level section ... The first level is useless. Drop it. While there, delete the option that limits the TOC to depth 3. Its actual depth was 3 before the patch, and is now 2. Signed-off-by: Markus Armbruster Message-ID: <20250404121413.1743790-5-armbru@redhat.com> Reviewed-by: Eric Blake --- docs/interop/qemu-qmp-ref.rst | 2 +- docs/interop/qemu-storage-daemon-qmp-ref.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/interop/qemu-qmp-ref.rst b/docs/interop/qemu-qmp-ref.rst index ef8792b53f..3bc1ca12b1 100644 --- a/docs/interop/qemu-qmp-ref.rst +++ b/docs/interop/qemu-qmp-ref.rst @@ -4,7 +4,7 @@ QEMU QMP Reference Manual ========================= .. contents:: - :depth: 3 + :local: .. qapi-doc:: qapi/qapi-schema.json :transmogrify: diff --git a/docs/interop/qemu-storage-daemon-qmp-ref.rst b/docs/interop/qemu-storage-daemon-qmp-ref.rst index d0228d63b8..dc7bde262a 100644 --- a/docs/interop/qemu-storage-daemon-qmp-ref.rst +++ b/docs/interop/qemu-storage-daemon-qmp-ref.rst @@ -2,7 +2,7 @@ QEMU Storage Daemon QMP Reference Manual ======================================== .. contents:: - :depth: 3 + :local: .. qapi-doc:: storage-daemon/qapi/qapi-schema.json :transmogrify: From e27608d05370a5c11f641bd96095afb2d06c5880 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 4 Apr 2025 14:14:07 +0200 Subject: [PATCH 05/11] docs/devel/qapi-code-gen: Improve the part on qmp-example directive Signed-off-by: Markus Armbruster Message-ID: <20250404121413.1743790-6-armbru@redhat.com> Reviewed-by: Eric Blake --- docs/devel/qapi-code-gen.rst | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index ad517349fc..25a46fafb6 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -1038,20 +1038,15 @@ default to "Example:". A simple QMP example:: # .. qmp-example:: - # :title: Using query-block # - # -> { "execute": "query-block" } - # <- { ... } + # -> { "execute": "query-name" } + # <- { "return": { "name": "Fred" } } More complex or multi-step examples where exposition is needed before or between QMP code blocks can be created by using the ``:annotated:`` directive option. When using this option, nested QMP code blocks must be entered explicitly with rST's ``::`` syntax. -Highlighting in non-QMP languages can be accomplished by using the -``.. code-block:: lang`` directive, and non-highlighted text can be -achieved by omitting the language argument. - For example:: # .. qmp-example:: @@ -1061,11 +1056,21 @@ For example:: # This is a more complex example that can use # ``arbitrary rST syntax`` in its exposition:: # - # -> { "execute": "query-block" } - # <- { ... } + # -> { "execute": "query-block" } + # <- { "return": [ + # { + # "device": "ide0-hd0", + # ... + # } + # ... + # ] } # # Above, lengthy output has been omitted for brevity. +Highlighting in non-QMP languages can be accomplished by using the +``.. code-block:: lang`` directive, and non-highlighted text can be +achieved by omitting the language argument. + Examples of complete definition documentation:: From bc361f2f9bc13455311d7ab296c60fe9dc93cff7 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 4 Apr 2025 14:14:08 +0200 Subject: [PATCH 06/11] docs/sphinx/qmp_lexer: Generalize elision syntax Accept "... lorem ipsum ..." in addition to "...". Signed-off-by: Markus Armbruster Message-ID: <20250404121413.1743790-7-armbru@redhat.com> Reviewed-by: Eric Blake --- docs/devel/qapi-code-gen.rst | 6 ++++-- docs/sphinx/qmp_lexer.py | 2 +- tests/qapi-schema/doc-good.json | 2 +- tests/qapi-schema/doc-good.out | 2 +- tests/qapi-schema/doc-good.txt | 2 +- 5 files changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 25a46fafb6..231cc0fecf 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -1029,7 +1029,9 @@ used. QMP Examples can be added by using the ``.. qmp-example::`` directive. In its simplest form, this can be used to contain a single QMP code block which accepts standard JSON syntax with additional server -directionality indicators (``->`` and ``<-``), and elisions (``...``). +directionality indicators (``->`` and ``<-``), and elisions. An +elision is commonly ``...``, but it can also be or a pair of ``...`` +with text in between. Optionally, a plaintext title may be provided by using the ``:title:`` directive option. If the title is omitted, the example title will @@ -1062,7 +1064,7 @@ For example:: # "device": "ide0-hd0", # ... # } - # ... + # ... more ... # ] } # # Above, lengthy output has been omitted for brevity. diff --git a/docs/sphinx/qmp_lexer.py b/docs/sphinx/qmp_lexer.py index a59de8a079..1bd1b81b70 100644 --- a/docs/sphinx/qmp_lexer.py +++ b/docs/sphinx/qmp_lexer.py @@ -24,7 +24,7 @@ class QMPExampleMarkersLexer(RegexLexer): 'root': [ (r'-> ', token.Generic.Prompt), (r'<- ', token.Generic.Prompt), - (r' ?\.{3} ?', token.Generic.Prompt), + (r'\.{3}( .* \.{3})?', token.Generic.Prompt), ] } diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index 0a4f139f83..14b808f909 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -212,7 +212,7 @@ # # -> "this example" # -# <- "has no title" +# <- ... has no title ... ## { 'command': 'cmd-boxed', 'boxed': true, 'data': 'Object', diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 5773f1dd6d..dc8352eed4 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -217,7 +217,7 @@ another feature -> "this example" - <- "has no title" + <- ... has no title ... doc symbol=EVT_BOXED body= diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt index cb37db606a..17a1d56ef1 100644 --- a/tests/qapi-schema/doc-good.txt +++ b/tests/qapi-schema/doc-good.txt @@ -264,7 +264,7 @@ Example:: -> "this example" - <- "has no title" + <- ... has no title ... "EVT_BOXED" (Event) From 6d7b3efc3fa83aec4cb09000893064907def811d Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 4 Apr 2025 14:14:09 +0200 Subject: [PATCH 07/11] docs/sphinx/qmp_lexer: Highlight elisions like comments, not prompts Signed-off-by: Markus Armbruster Message-ID: <20250404121413.1743790-8-armbru@redhat.com> Reviewed-by: Eric Blake --- docs/sphinx/qmp_lexer.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sphinx/qmp_lexer.py b/docs/sphinx/qmp_lexer.py index 1bd1b81b70..7b3b808d12 100644 --- a/docs/sphinx/qmp_lexer.py +++ b/docs/sphinx/qmp_lexer.py @@ -24,7 +24,7 @@ class QMPExampleMarkersLexer(RegexLexer): 'root': [ (r'-> ', token.Generic.Prompt), (r'<- ', token.Generic.Prompt), - (r'\.{3}( .* \.{3})?', token.Generic.Prompt), + (r'\.{3}( .* \.{3})?', token.Comment.Multiline), ] } From d0ae5a3058603d4b2c25984a3acb2ac83e025424 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 4 Apr 2025 14:14:10 +0200 Subject: [PATCH 08/11] qapi/qapi-schema: Update introduction for example notation The introduction explains example notation. The series merged in merge commit e6485190f77e (in 9.1) improved how they look in generated docs, but neglected to update the introduction accordingly. Do that now. Signed-off-by: Markus Armbruster Message-ID: <20250404121413.1743790-9-armbru@redhat.com> Reviewed-by: Eric Blake --- qapi/qapi-schema.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index c41c01eb2a..0d027d5017 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -26,10 +26,10 @@ # # Example: # -# :: +# .. qmp-example:: # -# -> data issued by the Client -# <- Server data response +# -> ... text sent by client (commands) ... +# <- ... text sent by server (command responses and events) ... # # Please refer to the # :doc:`QEMU Machine Protocol Specification ` From 9199d324a85cd3d4697b5907e804b903b5ce46e3 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 4 Apr 2025 14:14:11 +0200 Subject: [PATCH 09/11] qapi/qapi-schema: Address the introduction's bit rot Cut the crap that stopped making sense years ago. Adjust the remainder. Signed-off-by: Markus Armbruster Message-ID: <20250404121413.1743790-10-armbru@redhat.com> Reviewed-by: Eric Blake --- qapi/qapi-schema.json | 27 +++++++-------------------- 1 file changed, 7 insertions(+), 20 deletions(-) diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index 0d027d5017..7bc600bb76 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -3,37 +3,24 @@ ## # = Introduction # -# This document describes all commands currently supported by QMP. +# This manual describes the commands and events supported by the QEMU +# Monitor Protocol (QMP). # # For locating a particular item, please see the `qapi-qmp-index`. # -# Most of the time their usage is exactly the same as in the user -# Monitor, this means that any other document which also describe -# commands (the manpage, QEMU's manual, etc) can and should be -# consulted. -# -# QMP has two types of commands: regular and query commands. Regular -# commands usually change the Virtual Machine's state someway, while -# query commands just return information. The sections below are -# divided accordingly. -# -# It's important to observe that all communication examples are -# formatted in a reader-friendly way, so that they're easier to -# understand. However, in real protocol usage, they're emitted as a -# single line. -# -# Also, the following notation is used to denote data flow: -# -# Example: +# The following notation is used in examples: # # .. qmp-example:: # # -> ... text sent by client (commands) ... # <- ... text sent by server (command responses and events) ... # +# Example text is formatted for readability. However, in real +# protocol usage, its commonly emitted as a single line. +# # Please refer to the # :doc:`QEMU Machine Protocol Specification ` -# for detailed information on the Server command and response formats. +# for the general format of commands, responses, and events. ## { 'include': 'pragma.json' } From 5e03548bf222b0f8038dc61dbf0c93bd062025aa Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 4 Apr 2025 14:14:12 +0200 Subject: [PATCH 10/11] storage-daemon/qapi/qapi-schema: Add a proper introduction Contents adapted from qapi/qapi-schema.json. Signed-off-by: Markus Armbruster Message-ID: <20250404121413.1743790-11-armbru@redhat.com> Reviewed-by: Eric Blake --- storage-daemon/qapi/qapi-schema.json | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/storage-daemon/qapi/qapi-schema.json b/storage-daemon/qapi/qapi-schema.json index 2a562ee32e..0427594c98 100644 --- a/storage-daemon/qapi/qapi-schema.json +++ b/storage-daemon/qapi/qapi-schema.json @@ -14,10 +14,26 @@ # storage daemon. ## -# = QEMU storage daemon protocol commands and structs +# = Introduction # -# For a concise listing of all commands, events, and types in the QEMU -# storage daemon, please consult the `qapi-qsd-index`. +# This manual describes the commands and events supported by the QEMU +# storage daemon QMP. +# +# For locating a particular item, please see the `qapi-qsd-index`. +# +# The following notation is used in examples: +# +# .. qmp-example:: +# +# -> ... text sent by client (commands) ... +# <- ... text sent by server (command responses and events) ... +# +# Example text is formatted for readability. However, in real +# protocol usage, its commonly emitted as a single line. +# +# Please refer to the +# :doc:`QEMU Machine Protocol Specification ` +# for the general format of commands, responses, and events. ## From 8d41a7dfc2a8f21228b7f29314dd68ad0aa96d10 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 4 Apr 2025 14:14:13 +0200 Subject: [PATCH 11/11] qga/qapi-schema: Add a proper introduction Contents adapted from qapi/qapi-schema.json. Signed-off-by: Markus Armbruster Message-ID: <20250404121413.1743790-12-armbru@redhat.com> Reviewed-by: Eric Blake --- qga/qapi-schema.json | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index 35ec0e7db3..5316bfacbf 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -2,10 +2,24 @@ # vim: filetype=python ## -# = QEMU guest agent protocol commands and structs +# This manual describes the commands supported by the QEMU Guest +# Agent Protocol. # -# For a concise listing of all commands, events, and types in the QEMU -# guest agent, please consult the `qapi-qga-index`. +# For locating a particular item, please see the `qapi-qga-index`. +# +# The following notation is used in examples: +# +# .. qmp-example:: +# +# -> ... text sent by client (commands) ... +# <- ... text sent by server (command responses and events) ... +# +# Example text is formatted for readability. However, in real +# protocol usage, its commonly emitted as a single line. +# +# Please refer to the +# :doc:`QEMU Machine Protocol Specification ` +# for the general format of commands, responses, and events. ## { 'pragma': { 'doc-required': true } }