John Snow <js...@redhat.com> writes:
> On Fri, Jun 14, 2024, 6:55 AM Markus Armbruster <arm...@redhat.com> wrote:
>
>> John Snow <js...@redhat.com> writes:
>>
>> > If we parse all examples as QMP, we need them to conform to a standard
>> > so that they render correctly. Once the QMP lexer is active for
>> > examples, these will produce warning messages and fail the build.
>> >
>> > The QMP lexer still supports elisions, but they must be represented as
>> > the value "...", so two examples have been adjusted to support that
>> > format here.
>>
>> I think this could use a bit more context. I believe you're referring
>> to docs/sphinx/qmp_lexer.py. It describes itself as "a Sphinx extension
>> that provides a QMP lexer for code blocks."
>>
>
> That's our guy! I explain its use a bit more in ... some other patch,
> somewhere...
>
>
>> "If we parse all examples as QMP" and "Once the QMP lexer is active for
>> examples" suggests we're *not* using it for (some?) examples. So what
>> are we using it for?
>>
>
> My incremental backup doc makes use of it; you have to "opt in" to using
> the QMP lexer instead of the generic lexer.
The ".. code-block:: QMP" lines I can see in a few files? Namely:
docs/devel/s390-cpu-topology.rst
docs/interop/bitmaps.rst
docs/interop/qmp-spec.rst
> The example conversion patch later in this series opts all of the qapi docs
> into using it.
>
> ((Later, it's possible to make "Example::" choose the QMP lexer by default
> on any of our generated QMP pages. (and opting out would require explicit
> code-block syntax with the lexer of choice named.)))
The patch does two related things:
1. Fix invalid JSON. Doesn't need justification.
2. Normalize elisions to ... You pick ... because that's what
qmp_lexer.py wants.
Doing both in one patch is fine.
Perhaps
qapi: Fix invalid JSON in examples, and normalize elisions
A few examples elide part of the output. Normalize elision to
exactly ... Together with the JSON fixing, this enables use of
docs/sphinx/qmp_lexer.py to highlight the examples in a later patch.
>> > Signed-off-by: John Snow <js...@redhat.com>
>>
>> Patch looks lovely.
>>
>> Hat tip to Victor Toso, who fixed up most examples two years ago. Back
>> then we couldn't decide how to do elisions, so we left some unfixed.
>>
>
> Sorry I didn't chime in back then! "..." is arbitrary, but it's what we
> already use for the qmp lexer and in the incremental backup/bitmap docs, so
> I figured consistency was good.
It is.
> The QMP lexer has syntax support for ->, <- and ... and otherwise requires
> the examples to be valid JSON. It doesn't understand grammar, though, so
> it's kind of "dumb", but this is one small protection.
