| Message ID | 20250404121413.1743790-7-armbru@redhat.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | qapi: Documentation improvements | expand |
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.
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?)
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!
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)
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(-)