Re: [PATCH 11/11] docs: enable transmogrifier for QSD and QGA

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> On Thu, Mar 13, 2025 at 2:54 AM Markus Armbruster <armbru@redhat.com> wrote:
>
>> John Snow <jsnow@redhat.com> writes:
>>
>> > This also creates the `qapi-qsd-index` and `qapi-qga-index` QMP indices.
>> >
>> > Signed-off-by: John Snow <jsnow@redhat.com>
>>
>> [...]
>>
>> > diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
>> > index 995594aaf43..35ec0e7db31 100644
>> > --- a/qga/qapi-schema.json
>> > +++ b/qga/qapi-schema.json
>> > @@ -3,6 +3,9 @@
>> >
>> >  ##
>> >  # = QEMU guest agent protocol commands and structs
>> > +#
>> > +# For a concise listing of all commands, events, and types in the QEMU
>> > +# guest agent, please consult the `qapi-qga-index`.
>> >  ##
>> >
>> >  { 'pragma': { 'doc-required': true } }
>> > diff --git a/storage-daemon/qapi/qapi-schema.json b/storage-daemon/qapi/qapi-schema.json
>> > index f10c9494906..2a562ee32e5 100644
>> > --- a/storage-daemon/qapi/qapi-schema.json
>> > +++ b/storage-daemon/qapi/qapi-schema.json
>> > @@ -13,6 +13,14 @@
>> >  # the array type in the main schema, even if it is unused outside of the
>> >  # storage daemon.
>> >
>> > +##
>> > +# = QEMU storage daemon protocol commands and structs
>> > +#
>> > +# For a concise listing of all commands, events, and types in the QEMU
>> > +# storage daemon, please consult the `qapi-qsd-index`.
>> > +##
>> > +
>> > +
>> >  { 'include': '../../qapi/pragma.json' }
>> >
>> >  # Documentation generated with qapi-gen.py is in source order, with
>>
>> Compare qapi/qapi-schema.json:
>>
>>    # = Introduction
>>    #
>>    # This document describes all commands currently supported by QMP.
>>    #
>>    # For locating a particular item, please see the `qapi-qmp-index`.
>>    #
>>
>> Suggest to pick one phrasing and stick to it, unless there's a reason
>> for more than one.
>>
>
> Nope, just free-handing it. What's your favorite? ;)

Let me see...

Alright, I saw, and I hate what I saw.  But addressing that should not
be coupled to this series.  I'm going to take your patch as is, and
improve on top.

"But what exactly do you hate?" you might ask.  Have a look at how the
three rendered manuals look like.

1. QMP (docs/manual/interop/qemu-qmp-ref.html)

    QEMU QMP Reference Manual
    *************************


    Contents
    ^^^^^^^^

    * QEMU QMP Reference Manual

      * Introduction

      * QMP errors

      [More entries at this level, namely all the modules...]


    Introduction
    ============

    This document describes all commands currently supported by QMP.

    For locating a particular item, please see the 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:

       -> data issued by the Client
       <- Server data response

    Please refer to the QEMU Machine Protocol Specification for detailed
    information on the Server command and response formats.


    QMP errors
    ==========

    [...]

The manual has a single top-level section, named like the manual.  WTF?

The introduction reads fine, except it should be "all commands and
events".

2. QSD

    QEMU Storage Daemon QMP Reference Manual
    ****************************************


    Contents
    ^^^^^^^^

    * QEMU Storage Daemon QMP Reference Manual

      * QEMU storage daemon protocol commands and structs

      * Common data types

      [More entries at this level, namely all the modules...]


    QEMU storage daemon protocol commands and structs
    =================================================

    For a concise listing of all commands, events, and types in the QEMU
    storage daemon, please consult the QSD Index.


    Common data types
    =================

Same section structure WTF as above.

The introduction section is crap, starting with the title.

3. QGA

    QEMU Guest Agent Protocol Reference
    ***********************************


    Contents
    ^^^^^^^^

    * QEMU Guest Agent Protocol Reference

      * QEMU guest agent protocol commands and structs


    QEMU guest agent protocol commands and structs
    ==============================================

    For a concise listing of all commands, events, and types in the QEMU
    guest agent, please consult the QGA Index.

    Command guest-sync-delimited (Since: 1.1)

       Echo back a unique integer value, and prepend to response a leading
       sentinel byte (0xFF) the client can check scan for.

       [...]

    [More definitions...]

The section structure is completely useless.  Why bury the contents two
levels deep, with meaningless section titles?

Again, the introduction section is crap, starting with the title.