Generate an index-per-namespace for the QAPI domain. Due to a limitation
with Sphinx's architecture, these indices must be defined during setup
time and cannot be dynamically created on-demand when a namespace
directive is encountered.
Owing to that limitation, add a configuration value to conf.py that
specifies which QAPI namespaces we'll generate indices for.
Indices will be named after their namespace, e.g. the "QMP" namespace
will generate to "qapi-qmp-index.html" and can be referenced using
`qapi-qmp-index`.
Signed-off-by: John Snow
---
docs/conf.py | 3 +++
docs/sphinx/qapi_domain.py | 51 +++---
2 files changed, 40 insertions(+), 14 deletions(-)
diff --git a/docs/conf.py b/docs/conf.py
index a3f9fa63d94..175491148c3 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -161,6 +161,9 @@
"see also",
}
+# Due to a limitation in Sphinx, we need to know which indices to
+# generate in advance. Adding a namespace here allows that generation.
+qapi_namespaces = set()
# -- Options for HTML output --
diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py
index a8a85a2de36..c94af5719ca 100644
--- a/docs/sphinx/qapi_domain.py
+++ b/docs/sphinx/qapi_domain.py
@@ -8,11 +8,13 @@
from __future__ import annotations
import re
+import types
from typing import (
TYPE_CHECKING,
List,
NamedTuple,
Tuple,
+Type,
cast,
)
@@ -669,6 +671,7 @@ class QAPIIndex(Index):
name = "index"
localname = _("QAPI Index")
shortname = _("QAPI Index")
+namespace = ""
def generate(
self,
@@ -678,25 +681,20 @@ def generate(
content: Dict[str, List[IndexEntry]] = {}
collapse = False
-# list of all object (name, ObjectEntry) pairs, sorted by name
-# (ignoring the module)
-objects = sorted(
-self.domain.objects.items(),
-key=lambda x: x[0].split(".")[-1].lower(),
-)
-
-for objname, obj in objects:
+for objname, obj in self.domain.objects.items():
if docnames and obj.docname not in docnames:
continue
-# Strip the module name out:
-objname = objname.split(".")[-1]
+ns, _mod, name = QAPIDescription.split_fqn(objname)
+
+if self.namespace != ns:
+continue
# Add an alphabetical entry:
-entries = content.setdefault(objname[0].upper(), [])
+entries = content.setdefault(name[0].upper(), [])
entries.append(
IndexEntry(
-objname, 0, obj.docname, obj.node_id, obj.objtype, "", ""
+name, 0, obj.docname, obj.node_id, obj.objtype, "", ""
)
)
@@ -704,10 +702,14 @@ def generate(
category = obj.objtype.title() + "s"
entries = content.setdefault(category, [])
entries.append(
-IndexEntry(objname, 0, obj.docname, obj.node_id, "", "", "")
+IndexEntry(name, 0, obj.docname, obj.node_id, "", "", "")
)
-# alphabetically sort categories; type names first, ABC entries last.
+# Sort entries within each category alphabetically
+for category in content:
+content[category] = sorted(content[category])
+
+# Sort the categories themselves; type names first, ABC entries last.
sorted_content = sorted(
content.items(),
key=lambda x: (len(x[0]) == 1, x[0]),
@@ -780,6 +782,21 @@ def objects(self) -> Dict[str, ObjectEntry]:
ret = self.data.setdefault("objects", {})
return ret # type: ignore[no-any-return]
+def setup(self) -> None:
+namespaces = set(self.env.app.config.qapi_namespaces)
+for namespace in namespaces:
+new_index: Type[QAPIIndex] = types.new_class(
+f"{namespace}Index", bases=(QAPIIndex,)
+)
+new_index.name = f"{namespace.lower()}-index"
+new_index.localname = _(f"{namespace} Index")
+new_index.shortname = _(f"{namespace} Index")
+new_index.namespace = namespace
+
+self.indices.append(new_index)
+
+super().setup()
+
def note_object(
self,
name: str,
@@ -1019,6 +1036,12 @@ def setup(app: Sphinx) -> Dict[str, Any]:
"env", # Setting impacts parsing phase
types=set,
)
+app.add_config_value(
+"qapi_namespaces",
+set(),
+"env",
+types=set,
+)
app.add_domain(QAPIDomain)
return {
--
2.48.1
