1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
"""
QAPI domain extension.
"""
from __future__ import annotations
from typing import (
TYPE_CHECKING,
AbstractSet,
Any,
Dict,
NamedTuple,
Tuple,
)
from sphinx.domains import Domain, ObjType
from sphinx.locale import __
from sphinx.util import logging
if TYPE_CHECKING:
from sphinx.application import Sphinx
logger = logging.getLogger(__name__)
class ObjectEntry(NamedTuple):
docname: str
node_id: str
objtype: str
aliased: bool
class QAPIDomain(Domain):
"""QAPI language domain."""
name = "qapi"
label = "QAPI"
# This table associates cross-reference object types (key) with an
# ObjType instance, which defines the valid cross-reference roles
# for each object type.
# Actual table entries for module, command, event, etc will come in
# forthcoming commits.
object_types: Dict[str, ObjType] = {}
directives = {}
roles = {}
# Moved into the data property at runtime;
# this is the internal index of reference-able objects.
initial_data: Dict[str, Dict[str, Tuple[Any]]] = {
"objects": {}, # fullname -> ObjectEntry
}
indices = []
@property
def objects(self) -> Dict[str, ObjectEntry]:
ret = self.data.setdefault("objects", {})
return ret # type: ignore[no-any-return]
def note_object(
self,
name: str,
objtype: str,
node_id: str,
aliased: bool = False,
location: Any = None,
) -> None:
"""Note a QAPI object for cross reference."""
if name in self.objects:
other = self.objects[name]
if other.aliased and aliased is False:
# The original definition found. Override it!
pass
elif other.aliased is False and aliased:
# The original definition is already registered.
return
else:
# duplicated
logger.warning(
__(
"duplicate object description of %s, "
"other instance in %s, use :no-index: for one of them"
),
name,
other.docname,
location=location,
)
self.objects[name] = ObjectEntry(
self.env.docname, node_id, objtype, aliased
)
def clear_doc(self, docname: str) -> None:
for fullname, obj in list(self.objects.items()):
if obj.docname == docname:
del self.objects[fullname]
def merge_domaindata(
self, docnames: AbstractSet[str], otherdata: Dict[str, Any]
) -> None:
for fullname, obj in otherdata["objects"].items():
if obj.docname in docnames:
# Sphinx's own python domain doesn't appear to bother to
# check for collisions. Assert they don't happen and
# we'll fix it if/when the case arises.
assert fullname not in self.objects, (
"bug - collision on merge?"
f" {fullname=} {obj=} {self.objects[fullname]=}"
)
self.objects[fullname] = obj
def resolve_any_xref(self, *args: Any, **kwargs: Any) -> Any:
# pylint: disable=unused-argument
return []
def setup(app: Sphinx) -> Dict[str, Any]:
app.setup_extension("sphinx.directives")
app.add_domain(QAPIDomain)
return {
"version": "1.0",
"env_version": 1,
"parallel_read_safe": True,
"parallel_write_safe": True,
}
|