| Message ID | 20250313044312.189276-12-jsnow@redhat.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | docs/qapi: enable new guest-agent and storage-daemon docs | expand |
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.
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? ;)
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.
diff --git a/docs/conf.py b/docs/conf.py index 9a86e84a804..7b5712e122f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -164,7 +164,9 @@ # Due to a limitation in Sphinx, we need to know which indices to # generate in advance. Adding a namespace here allows that generation. qapi_namespaces = { + "QGA", "QMP", + "QSD", } # -- Options for HTML output ---------------------------------------------- diff --git a/docs/interop/qemu-ga-ref.rst b/docs/interop/qemu-ga-ref.rst index 032d4924552..19b5c7a5498 100644 --- a/docs/interop/qemu-ga-ref.rst +++ b/docs/interop/qemu-ga-ref.rst @@ -5,3 +5,5 @@ QEMU Guest Agent Protocol Reference :depth: 3 .. qapi-doc:: qga/qapi-schema.json + :transmogrify: + :namespace: QGA diff --git a/docs/interop/qemu-storage-daemon-qmp-ref.rst b/docs/interop/qemu-storage-daemon-qmp-ref.rst index 9fed68152f5..d0228d63b8d 100644 --- a/docs/interop/qemu-storage-daemon-qmp-ref.rst +++ b/docs/interop/qemu-storage-daemon-qmp-ref.rst @@ -5,3 +5,5 @@ QEMU Storage Daemon QMP Reference Manual :depth: 3 .. qapi-doc:: storage-daemon/qapi/qapi-schema.json + :transmogrify: + :namespace: QSD 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
This also creates the `qapi-qsd-index` and `qapi-qga-index` QMP indices. Signed-off-by: John Snow <jsnow@redhat.com> --- docs/conf.py | 2 ++ docs/interop/qemu-ga-ref.rst | 2 ++ docs/interop/qemu-storage-daemon-qmp-ref.rst | 2 ++ qga/qapi-schema.json | 3 +++ storage-daemon/qapi/qapi-schema.json | 8 ++++++++ 5 files changed, 17 insertions(+)