docs/sphinx/qapi_domain.py

6 # pylint: disable=too-many-lines
71 ) -> Tuple[nodes.field_name, nodes.field_body]:
73     docutils helper: unpack a field node in a type-safe manner.
98     ) -> tuple[str, str]:
102         # Cross-references that begin with a tilde adjust the title to
104         # was provided. This is a Sphinx-standard syntax; give it
105         # priority over QAPI-specific type markup below.
116             target = target[:-1]
122             target = target[1:-1]
125             # Don't mess with the title at all if it was explicitly set.
133             title = target.split(".")[-1]
143     ) -> Tuple[List[nodes.Node], List[nodes.system_message]]:
169     def handle_signature(self, sig: str, signode: desc_signature) -> Signature:
170         # pylint: disable=unused-argument
177         # render the signature; here we do nothing instead - the
181     def get_index_text(self, name: Signature) -> Tuple[str, str]:
187     def _get_context(self) -> Tuple[str, str]:
197     def _get_fqn(self, name: Signature) -> str:
213     ) -> None:
214         # pylint: disable=unused-argument
234         if "no-index-entry" not in self.options:
243     def split_fqn(name: str) -> Tuple[str, str, str]:
258     ) -> Tuple[str, ...]:
263     def _toc_entry_name(self, sig_node: desc_signature) -> str:
326     def get_signature_prefix(self) -> List[nodes.Node]:
334     def get_signature_suffix(self) -> List[nodes.Node]:
348     def handle_signature(self, sig: str, signode: desc_signature) -> Signature:
355         else in the content body with field lists.
379     def _add_infopips(self, contentnode: addnodes.desc_content) -> None:
380         # Add various eye-catches and things that go below the signature
381         # bar, but precede the user-defined content.
383         infopips.attributes["classes"].append("qapi-infopips")
386             source: str, content: Union[str, List[nodes.Node]], classname: str
387         ) -> None:
389             if isinstance(content, str):
390                 node.append(nodes.Text(content))
392                 node.extend(content)
393             node.attributes["classes"].extend(["qapi-infopip", classname])
400                 "qapi-deprecated",
407                 "qapi-unstable",
419                 "qapi-ifcond",
425     def _validate_field(self, field: nodes.field) -> None:
428         allowed_fields = set(self.env.app.config.qapi_allowed_fields)
447             # This is a special docfield, yet-to-be-processed. Catch
463             valid = ", ".join(sorted(set(typemap) | allowed_fields))
473     def transform_content(self, content_node: addnodes.desc_content) -> None:
489     def make_field(self, *args: Any, **kwargs: Any) -> nodes.field:
492         # Look for the characteristic " -- " text node that Sphinx
494         for node in ret.traverse(lambda n: str(n) == " -- "):
501             del par.children[:-1]
593     # pylint: disable=too-many-ancestors
598     # pylint: disable=too-many-ancestors
607     a pass-through for the content body. Named section titles are
608     allowed in the content body.
616     :opt no-index: Don't add cross-reference targets or index entries.
617     :opt no-typesetting: Don't render the content body (but preserve any
618        cross-reference target IDs in the squelched output.)
622        .. qapi:module:: block-core
623           :no-index:
624           :no-typesetting:
629     def run(self) -> List[Node]:
637         # Extract the content body of the directive:
638         assert isinstance(ret[-1], addnodes.desc)
639         desc_node = ret.pop(-1)
643         # Re-home node_ids so anchor refs still work:
660     def run(self) -> List[Node]:
672     # pylint: disable=too-few-public-methods
682     ) -> Tuple[List[Tuple[str, List[IndexEntry]]], bool]:
684         content: Dict[str, List[IndexEntry]] = {}
697             entries = content.setdefault(name[0].upper(), [])
706             entries = content.setdefault(category, [])
712         for category in content:
713             content[category] = sorted(content[category])
717             content.items(),
729     # This table associates cross-reference object types (key) with an
730     # ObjType instance, which defines the valid cross-reference roles
733     # e.g., the :qapi:type: cross-reference role can refer to enum,
735     # anything. Each object also gets its own targeted cross-reference role.
746     # e.g. .. qapi:module:: block-core
757     # These are all cross-reference roles; e.g.
758     # :qapi:cmd:`query-block`. The keys correlate to the names used in
773     # this is the internal index of reference-able objects.
775         "objects": {},  # fullname -> ObjectEntry
784     def objects(self) -> Dict[str, ObjectEntry]:
786         return ret  # type: ignore[no-any-return]
788     def setup(self) -> None:
789         namespaces = set(self.env.app.config.qapi_namespaces)
794             new_index.name = f"{namespace.lower()}-index"
810     ) -> None:
825                         "other instance in %s, use :no-index: for one of them"
835     def clear_doc(self, docname: str) -> None:
842     ) -> None:
849                     "bug - collision on merge?"
856     ) -> List[Tuple[str, ObjectEntry]]:
866         :param name: The name of the x-ref to resolve; may or may not
868         :param type: The role name of the x-ref we're resolving, if
904         def _search(needle: str) -> List[str]:
931             # Try searching for context-ns:*.name or context-ns:name
934             # Try searching for *:context-mod.name or context-mod.name
964     ) -> nodes.reference | None:
971             # but that will trigger on references to these built-in types,
975             # reference isn't to one of our built-in core types.
997                 __("more than one target found for cross-reference %r: %s"),
1018     ) -> List[Tuple[str, nodes.reference]]:
1034 def setup(app: Sphinx) -> Dict[str, Any]:
1038         set(),
1040         types=set,
1044         set(),
1046         types=set,