[v1] qapi: Documentation improvements

[PATCH 06/11] docs/sphinx/qmp_lexer: Generalize elision syntax

Posted by Markus Armbruster 8 months, 2 weeks ago

Accept "... lorem ipsum ..."  in addition to "...".

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 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)
-- 
2.48.1

Re: [PATCH 06/11] docs/sphinx/qmp_lexer: Generalize elision syntax

Posted by John Snow 8 months, 1 week ago

On Fri, Apr 4, 2025 at 8:14 AM Markus Armbruster <armbru@redhat.com> wrote:

> Accept "... lorem ipsum ..."  in addition to "...".
>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  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)
> --
> 2.48.1
>
>
Cool, sure!

ACK (Who is responsible for this now? Me?)

Re: [PATCH 06/11] docs/sphinx/qmp_lexer: Generalize elision syntax

Posted by Markus Armbruster 8 months, 1 week ago

John Snow <jsnow@redhat.com> writes:

> On Fri, Apr 4, 2025 at 8:14 AM Markus Armbruster <armbru@redhat.com> wrote:
>
>> Accept "... lorem ipsum ..."  in addition to "...".
>>
>> Signed-off-by: Markus Armbruster <armbru@redhat.com>

[...]

> Cool, sure!
>
> ACK (Who is responsible for this now? Me?)

Yup.

I posted the PR without waiting for your approval only because I really,
really want to get the introductions right for 10.0, and the
docs/sphinx/ is just a one-liner.  Hope you don't mind!

Re: [PATCH 06/11] docs/sphinx/qmp_lexer: Generalize elision syntax

Posted by Eric Blake 8 months, 1 week ago

On Fri, Apr 04, 2025 at 02:14:08PM +0200, Markus Armbruster wrote:
> Accept "... lorem ipsum ..."  in addition to "...".
> 
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
> @@ -1062,7 +1064,7 @@ For example::
>    #               "device": "ide0-hd0",
>    #               ...
>    #             }
> -  #             ...
> +  #             ... more ...
>    #          ] }

Nice.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.
Virtualization:  qemu.org | libguestfs.org