Currently, only the definition name is stored in the tree metadata; but
the node property is confusingly called "fullname". Rectify this by
always storing the FQN in the tree metadata.
... While we're here, re-organize the code in preparation for namespace
support to make it a bit easier to add additional components of the
FQN. With this change, there is now extremely little code left that's
taken directly from the Python domain :)
Signed-off-by: John Snow <js...@redhat.com>
---
docs/sphinx/qapi_domain.py | 64 +++++++++++++++++++++++++-------------
1 file changed, 42 insertions(+), 22 deletions(-)
diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py
index d52e7df7bc7..6b23fc73ef2 100644
--- a/docs/sphinx/qapi_domain.py
+++ b/docs/sphinx/qapi_domain.py
@@ -178,6 +178,25 @@ def get_index_text(self, name: Signature) -> Tuple[str,
str]:
# NB: this is used for the global index, not the QAPI index.
return ("single", f"{name} (QMP {self.objtype})")
+ def _get_context(self) -> str:
+ modname = self.options.get(
+ "module", self.env.ref_context.get("qapi:module", "")
+ )
+ assert isinstance(modname, str)
+ return modname
+
+ def _get_fqn(self, name: Signature) -> str:
+ modname = self._get_context()
+
+ # If we're documenting a module, don't include the module as
+ # part of the FQN; we ARE the module!
+ if self.objtype == "module":
+ modname = ""
+
+ if modname:
+ name = f"{modname}.{name}"
+ return name
+
def add_target_and_index(
self, name: Signature, sig: str, signode: desc_signature
) -> None:
@@ -187,14 +206,8 @@ def add_target_and_index(
assert self.objtype
- # If we're documenting a module, don't include the module as
- # part of the FQN.
- modname = ""
- if self.objtype != "module":
- modname = self.options.get(
- "module", self.env.ref_context.get("qapi:module")
- )
- fullname = (modname + "." if modname else "") + name
+ if not (fullname := signode.get("fullname", "")):
+ fullname = self._get_fqn(name)
node_id = make_id(
self.env, self.state.document, self.objtype, fullname
@@ -213,18 +226,21 @@ def add_target_and_index(
(arity, indextext, node_id, "", None)
)
+ @staticmethod
+ def split_fqn(name: str) -> Tuple[str, str]:
+ if "." in name:
+ module, name = name.split(".")
+ else:
+ module = ""
+
+ return (module, name)
+
def _object_hierarchy_parts(
self, sig_node: desc_signature
) -> Tuple[str, ...]:
if "fullname" not in sig_node:
return ()
- modname = sig_node.get("module")
- fullname = sig_node["fullname"]
-
- if modname:
- return (modname, *fullname.split("."))
-
- return tuple(fullname.split("."))
+ return self.split_fqn(sig_node["fullname"])
def _toc_entry_name(self, sig_node: desc_signature) -> str:
# This controls the name in the TOC and on the sidebar.
@@ -235,13 +251,19 @@ def _toc_entry_name(self, sig_node: desc_signature) ->
str:
return ""
config = self.env.app.config
- *parents, name = toc_parts
+ modname, name = toc_parts
+
if config.toc_object_entries_show_parents == "domain":
- return sig_node.get("fullname", name)
+ ret = name
+ if modname and modname != self.env.ref_context.get(
+ "qapi:module", ""
+ ):
+ ret = f"{modname}.{name}"
+ return ret
if config.toc_object_entries_show_parents == "hide":
return name
if config.toc_object_entries_show_parents == "all":
- return ".".join(parents + [name])
+ return sig_node.get("fullname", name)
return ""
@@ -312,11 +334,9 @@ def handle_signature(self, sig: str, signode:
desc_signature) -> Signature:
As such, the only argument here is "sig", which is just the QAPI
definition name.
"""
- modname = self.options.get(
- "module", self.env.ref_context.get("qapi:module")
- )
+ modname = self._get_context()
- signode["fullname"] = sig
+ signode["fullname"] = self._get_fqn(sig)
signode["module"] = modname
sig_prefix = self.get_signature_prefix()
if sig_prefix:
--
2.48.1
