On Sun, Mar 9, 2025 at 5:13 PM Markus Armbruster <armbru@redhat.com> wrote:
> John Snow <jsnow@redhat.com> writes:
>
> > We are not enabling the transmogrifier for QSD or QGA yet because we
> > don't (yet) have a way to create separate indices, and all of the
> > definitions will bleed together, which isn't so nice.
> >
> > For now, QMP is better than nothing at all!
> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
> > ---
> > docs/interop/qemu-qmp-ref.rst | 1 +
> > qapi/qapi-schema.json | 2 ++
> > 2 files changed, 3 insertions(+)
> >
> > diff --git a/docs/interop/qemu-qmp-ref.rst
> b/docs/interop/qemu-qmp-ref.rst
> > index f94614a0b2f..e95eeac45e2 100644
> > --- a/docs/interop/qemu-qmp-ref.rst
> > +++ b/docs/interop/qemu-qmp-ref.rst
> > @@ -7,3 +7,4 @@ QEMU QMP Reference Manual
> > :depth: 3
> >
> > .. qapi-doc:: qapi/qapi-schema.json
> > + :transmogrify:
> > diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json
> > index 2877aff73d0..4475e81cc3e 100644
> > --- a/qapi/qapi-schema.json
> > +++ b/qapi/qapi-schema.json
> > @@ -5,6 +5,8 @@
> > #
> > # This document describes all commands currently supported by QMP.
> > #
> > +# For locating a particular item, please see the `qapi-index`.
> > +#
>
> ```qapi-index``` becomes a link in HTML. The link takes me to an index
> page. Two observations:
>
> * The index page appears not to be linked from the navigation thingie on
> the left. Searching for "QAPI Index" there doesn't find it, either.
>
We'll have to find a way to add it, and where. I don't actually know how
right away. We can discuss this on the namespace patches.
>
> * The index is structured into sections titled Alternates, Commands |
> Enums, Events, Modules, Objects, A, ... Z. As I scrolled down
> quickly, the transition from Objects to A confused me briefly: I
> didn't immediately understand that A, ... Z contains the union of
> everything above sorted into letter buckets.
>
Yes, it's weird. I don't have a lot of control over how the index is laid
out, but felt that it was very useful to have both by type (especially to
see commands and events all in one place) and a "classic" alphabetical
reference.
I don't think I can make any meaningful adjustments to this before rc0, I
apologize. Let's revisit soon on the namespace patches, because each
namespace will need its own index and it's a good time to discuss how to
lay them out.
>
> > # 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
>
>