@@ -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 ----------------------------------------------
@@ -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 {
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 <jsnow@redhat.com> --- docs/conf.py | 3 +++ docs/sphinx/qapi_domain.py | 51 +++++++++++++++++++++++++++----------- 2 files changed, 40 insertions(+), 14 deletions(-)