John Snow <[email protected]> writes:
> Signed-off-by: John Snow <[email protected]>
> ---
> docs/sphinx/qapi_domain.py | 95 ++++++++++++++++++++++++++++++++++++++
> 1 file changed, 95 insertions(+)
>
> diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py
> index a445150ae59..183d9a2766f 100644
> --- a/docs/sphinx/qapi_domain.py
> +++ b/docs/sphinx/qapi_domain.py
> @@ -18,7 +18,9 @@
> )
>
> from docutils import nodes
> +from docutils.parsers.rst import directives
>
> +from compat import KeywordNode, SpaceNode
> from sphinx import addnodes
> from sphinx.addnodes import desc_signature, pending_xref
> from sphinx.directives import ObjectDescription
> @@ -40,6 +42,7 @@
> from sphinx.application import Sphinx
> from sphinx.builders import Builder
> from sphinx.environment import BuildEnvironment
> + from sphinx.util.typing import OptionSpec
>
> logger = logging.getLogger(__name__)
>
> @@ -99,6 +102,8 @@ def process_link(
> return title, target
>
>
> +# Alias for the return of handle_signature(), which is used in several
> places.
> +# (In the Python domain, this is Tuple[str, str] instead.)
> Signature = str
>
>
> @@ -158,6 +163,96 @@ def add_target_and_index(
> )
>
>
> +class QAPIObject(QAPIDescription):
> + """
> + Description of a generic QAPI object.
> +
> + It's not used directly, but is instead subclassed by specific directives.
> + """
> +
> + # Inherit some standard options from Sphinx's ObjectDescription
> + option_spec: OptionSpec = ( # type:ignore[misc]
> + ObjectDescription.option_spec.copy()
> + )
> + option_spec.update(
> + {
> + # Borrowed from the Python domain:
> + "module": directives.unchanged, # Override contextual module
> name
> + }
> + )
> +
> + def get_signature_prefix(self) -> List[nodes.Node]:
> + """Returns a prefix to put before the object name in the
> signature."""
Recommend imperative mood: Return a prefix
> + assert self.objtype
> + return [
> + KeywordNode("", self.objtype.title()),
> + SpaceNode(" "),
> + ]
> +
> + def get_signature_suffix(self) -> List[nodes.Node]:
> + """Returns a suffix to put after the object name in the signature."""
Likewise.
> + return []
> +
> + def handle_signature(self, sig: str, signode: desc_signature) ->
> Signature:
> + """
> + Transform a QAPI definition name into RST nodes.
Like you do here.
> +
> + This method was originally intended for handling function
> + signatures. In the QAPI domain, however, we only pass the
> + definition name as the directive argument and handle everything
> + else in the content body with field lists.
> +
> + 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")
> + )
> +
> + signode["fullname"] = sig
> + signode["module"] = modname
> + sig_prefix = self.get_signature_prefix()
> + if sig_prefix:
> + signode += addnodes.desc_annotation(
> + str(sig_prefix), "", *sig_prefix
> + )
> + signode += addnodes.desc_name(sig, sig)
> + signode += self.get_signature_suffix()
> +
> + return sig
> +
> + 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("."))
> +
> + def _toc_entry_name(self, sig_node: desc_signature) -> str:
> + # This controls the name in the TOC and on the sidebar.
> +
> + # This is the return type of _object_hierarchy_parts().
> + toc_parts = cast(Tuple[str, ...], sig_node.get("_toc_parts", ()))
> + if not toc_parts:
> + return ""
> +
> + config = self.env.app.config
> + *parents, name = toc_parts
> + if config.toc_object_entries_show_parents == "domain":
> + return sig_node.get("fullname", name)
> + if config.toc_object_entries_show_parents == "hide":
> + return name
> + if config.toc_object_entries_show_parents == "all":
> + return ".".join(parents + [name])
> + return ""
> +
> +
> class QAPIModule(QAPIDescription):
> """
> Directive to mark description of a new module.
