Re: [PATCH v2 12/62] docs/qapi-domain: add QAPIObject class

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  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.