From 23d017ca84c82ebae6988b73f0675a0a4f539bca Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 4 Apr 2025 14:14:03 +0200 Subject: 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(-) (limited to 'docs/devel') 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', -- cgit 1.4.1 From e27608d05370a5c11f641bd96095afb2d06c5880 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 4 Apr 2025 14:14:07 +0200 Subject: 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(-) (limited to 'docs/devel') 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:: -- cgit 1.4.1 From bc361f2f9bc13455311d7ab296c60fe9dc93cff7 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 4 Apr 2025 14:14:08 +0200 Subject: 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(-) (limited to 'docs/devel') 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) -- cgit 1.4.1