[PATCH 0/1] Sphinx: refactor QAPI indices

[PATCH 0/1] Sphinx: refactor QAPI indices

[John Snow]

RFC quality - what do we think about this style of index vs the one we
currently have?

John Snow (1):
  docs/qapi-domain: Improve QAPI indices

 docs/sphinx/qapi_domain.py | 51 +++++++++++++++++++++++++++-----------
 1 file changed, 37 insertions(+), 14 deletions(-)

-- 
2.48.1

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

[John Snow]

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 <jsnow@redhat.com>
---
 docs/sphinx/qapi_domain.py | 51 +++++++++++++++++++++++++++-----------
 1 file changed, 37 insertions(+), 14 deletions(-)

diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py
index c94af5719ca..d844493c5cb 100644
--- a/docs/sphinx/qapi_domain.py
+++ b/docs/sphinx/qapi_domain.py
@@ -679,37 +679,60 @@ def generate(
     ) -> Tuple[List[Tuple[str, List[IndexEntry]]], bool]:
         assert isinstance(self.domain, QAPIDomain)
         content: Dict[str, List[IndexEntry]] = {}
-        collapse = False
+        collapse = bool(not self.namespace)
 
-        for objname, obj in self.domain.objects.items():
+        module_index: Dict[str, List[IndexEntry]] = {}
+        type_index: Dict[str, List[IndexEntry]] = {}
+
+        for objname, obj in sorted(
+            self.domain.objects.items(),
+            key=lambda x: QAPIDescription.split_fqn(x[0])[2].lower(),
+        ):
             if docnames and obj.docname not in docnames:
                 continue
 
-            ns, _mod, name = QAPIDescription.split_fqn(objname)
+            ns, mod, name = QAPIDescription.split_fqn(objname)
 
-            if self.namespace != ns:
+            if self.namespace and self.namespace != ns:
                 continue
 
-            # Add an alphabetical entry:
+            # Index alphabetally on name only
             entries = content.setdefault(name[0].upper(), [])
+            extra = obj.objtype if self.namespace else f"{obj.objtype}, {ns}"
             entries.append(
                 IndexEntry(
-                    name, 0, obj.docname, obj.node_id, obj.objtype, "", ""
+                    name, 0, obj.docname, obj.node_id, extra, "", ""
                 )
             )
 
-            # Add a categorical entry:
-            category = obj.objtype.title() + "s"
-            entries = content.setdefault(category, [])
+            # Sub-index by-type
+            entries = type_index.setdefault(obj.objtype.title(), [])
+            extra = "" if self.namespace else ns
             entries.append(
-                IndexEntry(name, 0, obj.docname, obj.node_id, "", "", "")
+                IndexEntry(name, 2, obj.docname, obj.node_id, extra, "", "")
             )
 
-        # Sort entries within each category alphabetically
-        for category in content:
-            content[category] = sorted(content[category])
+            # Sub-index by-module
+            if mod:
+                category = mod if self.namespace else f"{mod}, {ns}"
+                entries = module_index.setdefault(category, [])
+                entries.append(
+                    IndexEntry(
+                        name, 2, obj.docname, obj.node_id, obj.objtype, "", ""
+                    )
+                )
 
-        # Sort the categories themselves; type names first, ABC entries last.
+        for key, indices in sorted(type_index.items()):
+            entries = content.setdefault("By type", [])
+            entries.append(IndexEntry(key, 1, "", "", "", "", ""))
+            entries.extend(indices)
+
+        for key, indices in sorted(module_index.items()):
+            entries = content.setdefault("By module", [])
+            entries.append(IndexEntry(key, 1, "", "", "", "", ""))
+            entries.extend(indices)
+
+        # Sort the categories themselves; meta-categories first.
         sorted_content = sorted(
             content.items(),
             key=lambda x: (len(x[0]) == 1, x[0]),
-- 
2.48.1

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

[Daniel P. Berrangé]

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.

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.

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. I'm not convinced we need
the modules in the index.


> 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 ?

> 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.


With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

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

[Markus Armbruster]

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.

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

[John Snow]

[-- Attachment #1: Type: text/plain, Size: 6932 bytes --]

On Mon, Jun 2, 2025 at 7:16 AM Daniel P. Berrangé <berrange@redhat.com>
wrote:

> 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.
>

I'm assuming here that you are opposing the "by module" categorization
specifically.

Fair enough. Markus has said similar things; that the split by module is
more of a sin of necessity than a genuine categorization. I suppose in my
mind's eye it is my hope that they WOULD be useful for grouping like
commands, structures, and events by topic. I admit they are not necessarily
strictly adherent to that idea at the moment.

However, I think it's *conceptually* useful to group together, say, "block
related things" into a block topic. Modules may not fit this 1:1 at
current, but it's the best we have.

If there's opposition to doing it in this manner, I cede, but still
maintain that grouping things by topic would be superior to a flat list of
just absolutely everything.


>
> 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.
>

Keep in mind that once the "inliner" is merged, the great majority of
"internal" structures will be omitted from this index. The exact definition
of what is elided is hard for me to describe formally, but: Any object that
is currently referenced only via "...The members of ..." will be omitted,
as the information relating to that definition will be inlined into the
appropriate command/event instead.

This will also by definition exclude entities that aren't referenced at
all, such as internal definitions we use for QOM/QDEV and similar purposes.

Due to a limitation in how I present alternates (i.e. via reference to the
type and not by inlining the choices/types), alternates are one of the few
types whose internal details remain even after the inliner is merged. This
isn't a fundamental barrier, just where the cutting room knife made the
excision, and can be remedied in the future.

The algorithm for what is visible is something like the following:

1. All entities are hidden by default.
2. All commands and events are marked visible.
3. All member types belonging to a visible entity (commands, events) are
marked as visible; i.e. if an event uses an enum or a command takes a
compound object as an argument, those entities become visible in the
documentation, even though the name of that type is an "internal detail".
This is because I do not have a system in place for presenting recursive
structures, and it is currently easiest to link to these types by
reference, necessitating their visibility. This marking is carried out
recursively.
4. All return types, currently, are marked visible. In the future we may
inline return structures in a manner similar to members, but we do not do
so, yet.

This isn't enough to remove *all* internal types, but it does get a lion's
share of them and thins the documentation considerably. I don't have
numbers on hand at present, but when I get these prerequisite series out of
the way, I can enumerate them.


>
> 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.
>

Yes; but that's how indices are at times: multiple things are listed in
multiple places to facilitate lookup. It is not really meant to be space
efficient.

In my case, the things I really truly care about are:

(1) A true alphabetical list of all symbols we have documented, and
(2) A list of all events and commands, specifically.

Everything else more or less just comes along for the ride by parallel;
making an index for events/commands inherently creates an index for
objects, enums, etc. I didn't see a need to specifically exclude them.


>
> 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. I'm not convinced we need
> the modules in the index.
>

That'd be cool! Unfortunately I'm going to reply here with the dreaded
"patches welcome". I'm worried I don't have the mandate to spend much more
time on this project than I already have... :(

If you'd like to take a crack at it, I would be happy to advise.


>
>
> > 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 ?
>

Maybe! This patchset is one of those cases where I went to fix one thing
and got carried away... If I can extract just this fix by its lonesome I
will do so. I admit that I forget right now how easy that is to do, or if
it relies on my restructuring of other elements.

... It's probably easy enough to rewrite, anyway.


>
> > 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 suppose so. If we do not find the master index useful, we could go the
other route and eliminate it entirely, leaving only the domain-specific
indices. I recall Markus at one point assumed the master index to work as
this patch makes it work, so I just closed the loop here. The way it
currently actually works is that the master index only indexes items that
have no associated domain, which turns out to be essentially nothing.


>
>
> With regards,
> Daniel
> --
> |: https://berrange.com      -o-
> https://www.flickr.com/photos/dberrange :|
> |: https://libvirt.org         -o-
> https://fstop138.berrange.com :|
> |: https://entangle-photo.org    -o-
> https://www.instagram.com/dberrange :|
>
>

[-- Attachment #2: Type: text/html, Size: 9534 bytes --]

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

[John Snow]

[-- Attachment #1: Type: text/plain, Size: 2925 bytes --]

On Fri, May 23, 2025 at 2:08 PM John Snow <jsnow@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 <jsnow@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

[-- Attachment #2: Type: text/html, Size: 4571 bytes --]

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

[Markus Armbruster]

I refreshed my memory on this.  It's been a while.  Instead of replying
to your replies long after you wrote them, I'm going to write up my
thoughts in one place.


= General observations =

* We have three QAPI-generated manuals: QEMU QMP Reference Manual, QEMU
  Storage Daemon QMP Reference Manual, QEMU Guest Agent Protocol
  Reference.

* We generate an index for each manual: qapi-qmp-index.html,
  qapi-qst-index.html, qapi-qga-index.html.

* The doc generator does not link to these indexes by itself.  Instead,
  each manual links to its index in its introduction section.  This
  makes the index really easy to miss.  Even if you're aware, jumping to
  the index is bothersome once this lone link is out of sight.  Until
  that changes, the practical value of improvements to the index is in
  doubt.  Doesn't mean improvements should not be made, only that they
  better be cheap.

* You're proposing to additionally generate a "main" QAPI index
  qapi-index.html for everything documented in any QAPI-generated
  manual.  Not linked from anywhere.

* Modules let developers structure the schema and the generated code.
  They are not a thing at the QMP interface.  Letting such internals
  bleed into QMP documentation is *wrong*.  The excuse for doing it
  anyway is that the module tree is close to the section tree in
  practice, and we can use the modules (which are readily available in
  the doc generator) as an approximation for sections (which we don't
  have there at this time).


= Indexes before the patch =

An index page starts with links

    Alternates | Commands | Enums | Events | Modules | Objects | A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z 

Then we have flat lists of the alternates, commands, enums, events,
modules, objects, entities starting with "A" or "a", ..., "Z" or "z".
Each list is alphabetically sorted.

The links at the top take you to the heading of the respective list.

The list entries link to entity documentation, except for "Modules",
which link to the beginning of the doc generated for a QAPI module.
The entries under "A", ..., "Z" have a (meta-type) suffix.

Every entity is listed twice, once under its meta-type (Alternates,
Commands, Enums, Events, Objects), and once under its first letter.


= Indexes after the patch =

An index page starts with links

    By module | By type | A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

Then a two level list module / entity name (meta-type) linking to the
entity's doc.  Link "By module" takes you to its heading.

Then a two level list meta-type / entity name linking to the entity's
doc.  Link "By type" takes you to its heading.  This replaces the flat
lists Alternates, Commands, Enums, Events, Objects.

In both two level lists the outer level is collapsible.

Then flat lists "A", ..., "Z" as before.

Flat list "Modules" is gone.

The links at the top take you to the heading of the respective list.

Every entity is listed twice, once under its meta-type under "By type",
and once under its first letter.

The lists are now sorted case-insensitively.


= Critique =

Here's the one question that matters: what are readers trying to do when
they use the index page?

Assuming they find the index page in the first place (see "lone link"
under "General observations" above), but that issue is out of scope
here.

I believe readers use the index to jump to the doc for X, where X is
something they encountered in the QMP interface.

I don't think they'll use the index to jump to the doc of an Y they
encounter in documentation, because that Y will be a link.

X obviously includes commands and events.

I doubt it includes types.  Type names are not a thing in the QMP
interface.  You run into them only in documentation, but again, they are
links there.

We should make looking up a command / event as easy and quick as we can.

Let's examine how users can navigate to the index entry that takes them
to the command / event doc.

Before the patch:

1. Find the index page somehow (out of scope here).

2. Click on Commands / Events.  For commands, can instead visually skip
   over the alternates (which is just a few lines) to Commands.

3. Visually scan an alphabetically sorted list of ~250 commands (almost
   seven screen-fulls for me) or ~50 events (a bit over one).

Alternatively:

2. Click on the letter the command / event starts with.

3. Visually scan an alphabetically sorted list of up to ~200 entries
   (five screen-fulls for me).

Alternatively:

2. Have the browser search the index page for the name.

Alternatively:

1. Screw the index, search the entire manual (single page) for the name.

After the patch:

1. Same.

2. Click on "By type".  If you can somehow divine that's where the
   commands / events hide.

3. For commands, visually skip over the alternates (which is just a few
   lines) to Command (could also collapse Alternate, but why bother).

   For events, either scroll down a lot looking for the events, or
   search for "event" (for me, that jumps right back to the top of the
   page to show me the first event under "By modules").  Could also
   collapse Alternate, Command, and Enum, but most likely just give up
   and try an alternative.

4. As before, visually scan an alphabetically sorted list of ~250
   commands (almost seven screen-fulls for me) or ~50 events (a bit over
   one).

The alternatives are unaffected by the patch.

I'm afraid the patch makes the index harder to use.

Minor quibbles:

* The "type" in "By type" is wrong.  It's by QAPI meta-type, which is
  not the same as QAPI type.  Casual readers will likely not be familiar
  with the term "meta-type".  Calling the thing type risks confusion
  nevertheless.

* The Modules sub-index before the patch is useless.  The navigation bar
  on the left is much, much easier to use.  It also shows the *actual*
  section structure, not an approximation.

* The "By Modules" index after the patch is debatable.

* I can't see a use for the "main" QAPI index.


= Recommendations =

* Consider dropping types from the index entirely.  This would make
  navigating to commands and events via first letter links *much*
  easier.  No need for Commands and Events lists, the "A", ..., "Z"
  suffice.

* Else, keep an obvious, one click path from top of index page to
  commands and to events.

  However, the list of commands is too long to quickly scan visually.
  Consider breaking it up by first letter.

* Keep the switch to case-insensitive sorting.

* Definitely drop the Modules sub-index.  I don't care for the "By
  modules" thing, either.  The navigation bar on the left does that job
  better.

* Drop the "main" QAPI index.

* Out of scope for this patch: a manual's index page should be easy to
  reach from anywhere in the manual.


Thoughts?

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

[Markus Armbruster]

Alright, that was a tad long.  Here's the shortest feedback I can give.

Thesis: the prime use case for the index is looking up commands and
events.  See my long reply for why.

Usability baseline: an index page with links "A", ... "Z" at the top,
each linking to a flat list of commands and events starting with that
letter, in case-insensitive alphabetical order.

The longest list is "Q": 83 entries.  Most lists are 20 entries or less.

Whatever index page design we choose, it should not be substantially
worse in usability for the prime use case than this baseline.