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

[John Snow <jsnow@redhat.com>]

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