Re: [PATCH 1/1] docs/qapi-domain: Improve QAPI indices

[Markus Armbruster <armbru@redhat.com>]

Daniel P. Berrangé <berrange@redhat.com> writes:

> On Fri, May 23, 2025 at 02:08:09PM -0400, John Snow wrote:
>> This patch changes the "by type" categorization in favor of using
>> sub-categories of a literal "By type" category instead. A new "By
>> module" categorization is also added that follows a similar pattern.
>
> I'm not much of a fan of this. IMHO unless you are looking at the
> module(s) for the subsystem you are the maintainer of, the split
> of definitions across modules comes across as somewhat arbitrary
> and unpredictable.

We have two parallel structures: QAPI modules and reST sections.

QAPI modules are for developers working on the QAPI schema[1].

reST sections are for readers of the documentation generated from the
QAPI schema.

We intentionally refrained from tying the two together more than
necessary.

The generated documentation is in an order defined by the include
directives.  To get the order you want, you may have to juggle include
directives, and maybe even split up modules.  If this ever gets too
bothersome, we'll provide some other way to order things[2].

You can then add any section structure you want.  You could even start a
section in the middle of one module, and end it in the middle of a later
module.  That would be silly, of course.  My point is: the section
structure need not mirror the module structure.

What does this mean for structuring the generated documentation's index?
If we want to structure it, we should use section structure, not module
structure.

> Looking at this from the POV of a consumer of QMP, our entrypoint
> to research is either a command name or an event name.
>
> The data type names of enums/alternates/objects are an internal
> QEMU detail that's not part of the public API.

Good observation.  I'd expect readers will want to use the index to look
up the names present in the external interface (commands and events).
Once they found them, they'll likely need to look up types mentioned
there, but they'll want to do so by following links, not going back to
the index.

> If we consider the index currently:
>
>   Alternates | Commands | Enums | Events | Modules | Objects | A | .... | Z
>
> The A ... Z bits link to a mix of all type names, which is a bit
> overwhealming.
>
> At the same time the page is twice as big as it needs to be
> as the same info is repeated under the A-Z index and the
> other per-type indexes.
>
> I think what would help would be to make the index dynamic
>
> eg
>
>   A | B | C | D | E | ... | X | Y | Z
>
>   [ ] Show internal types 
>
> The A-Z index would default to showing commands and events.
> Selecting the "Types" checkbox would toggle display of the
> alternate/enum/object names, which could be done via having
> a CSS class on each index entry, and javascript which just
> toggles 'display: none' / 'display: block' CSS property on
> the elements with the given class.

Hiding types by default makes sense to me.  How exactly to do that is up
to the developer.  Even something as simple & stupid as a link to an
alternate index page could work.

>                                    I'm not convinced we need
> the modules in the index.

Me neither.  See my argument above.

>> Alphabetical sorting has been improved and will sort in a case
>> insensitive manner for all categories, now.
>
> This is trivial and nice and could be a standalone fix ?

Yes, please :)

>> Lastly, the "main" QAPI Index (qapi-index.html) is altered to index
>> *everything* from all namespaces, adding disambiguation where necessary
>> to do so.
>
> This looks a bit wierd having the same types and modules repeated
> multiple times.

I'm not sure such an index is useful.

> With regards,
> Daniel


[1] Why are modules useful for developers?

The QAPI schema used to be monolithic: one input file
(qapi-schema.json), one output file of each kind (qapi-commands.c,
qapi-events.c, qapi-introspect.c, qapi-types.c, qapi-visit.c, ...).

A single input file is unwiedly, and defeats the MAINTAINERS file.  So
we added support for splitting it up into modules (commit a719a27c824
"qapi: Add a primitive to include other files from a QAPI schema file",
May 2014), and over several years moved *everything* from
qapi-schema.json to submodules it includes.

A single output file per kind eventually took us to "touch the QAPI
schema, recompile the world".  So I changed it to generate one output
file per module for the kinds where that makes sense (commit 252dc3105fc
"qapi: Generate separate .h, .c for each module", Feb 2018).


[2] If the order within a module makes the generated documentation hard
to read, it'll probably make the source file hard to read, too.  So fix
that.