motorhead/qemu
1
0
Fork 0
mirror of https://github.com/Motorhead1991/qemu.git synced 2025-07-27 04:13:53 -06:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs/qapi-domain: add namespaced index support

Browse source 
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>
Message-ID: <20250313044312.189276-9-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
This commit is contained in:
John Snow 2025-03-13 00:43:09 -04:00 • committed by Markus Armbruster
parent 7127e14f15
commit 25d44f57e1
2 changed files with 40 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

51
docs/sphinx/qapi_domain.py
View file

@ -8,11 +8,13 @@ QAPI domain extension.
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 @@ class QAPIIndex(Index):
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 @@ class QAPIIndex(Index):
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 @@ class QAPIDomain(Domain):
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 {