On Fri, May 23, 2025 at 2:08 PM John Snow <js...@redhat.com> 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. > > Alphabetical sorting has been improved and will sort in a case > insensitive manner for all categories, now. > > Lastly, the "main" QAPI Index (qapi-index.html) is altered to index > *everything* from all namespaces, adding disambiguation where necessary > to do so. > > Signed-off-by: John Snow <js...@redhat.com> > ... So, what would we like to keep here and what would we like to scrap? I'm basically fine either way, I just need to plan for what I'm going to clean up and submit and what I'm going to scrap. Not against adding a "TODO" for a later addition or a GSoC/Outreachy project etc either. I recall that we want the alphabetization fix no matter what, so I will do that. What about everything else? Before this patch, what we have currently, is: https://www.qemu.org/docs/master/qapi-qmp-index.html > Alternates | Commands | Enums | Events | Modules | Objects | A | ... | Z Entries in Alternates/Commands/Enums/Events/Modules/Objects are just the name. Entries under A..Z have a (type) suffix that clarifies what type of entry it is. There is no "global" qapi index, and any definitions that don't get included in a "namespace" will actually just be dropped. After this patch, the top level categories we have are: > By module | By type | A | ... | Z with "By module" having collapsible sections for each module, with entries that use the (type) suffix. and "By type" split into collapsible subsections for Alternate/Command/Enum/Event/Module/Object, entries have no suffix. The alphabetical entries cover absolutely everything and use the "(type)" suffix. The other major change creates a "global QAPI" index, which I only really created for the sake of completionism, just in case you really wanted to know every last thing about QMP that we offer all in one place. - By module, with subcategories being named "module, namespace" instead of just "module". Individual entries are suffixed with "(type)". - By type, subcategories have no suffix, but individual entries have a "(namespace)" suffix. - Alphabetical entries use a "(type, namespace)" suffix. One thing I'll volunteer that I don't actually like is that there's no way to hyperlink specifically to the list of commands/events in particular, though I do kind of like that the subsections are collapsible and I like that two-tier organization. I am not currently aware of any mechanisms to help make the indices fancier, and probably cannot afford to spend time investigating it further. Is consensus to just apply the alphabetization fix by itself and leave it at that for now? --js
