John Snow <js...@redhat.com> writes:
> This class is a generic, top-level directive for documenting some kind
> of QAPI thingamajig that we expect to go into the Index. This class
> doesn't do much by itself, and it isn't yet associated with any
> particular directive.
>
> Only handle_signature() is defined in the base class; get_index_text and
> add_target_and_index are new methods defined here; they are based
> heavily on the layout and format of the Python domain's general object
> class.
>
> Signed-off-by: John Snow <js...@redhat.com>
> ---
> docs/sphinx/qapi_domain.py | 65 ++++++++++++++++++++++++++++++++++++--
> 1 file changed, 63 insertions(+), 2 deletions(-)
>
> diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py
> index 49d42c0921c..0365891f354 100644
> --- a/docs/sphinx/qapi_domain.py
> +++ b/docs/sphinx/qapi_domain.py
> @@ -14,11 +14,13 @@
> NamedTuple,
> Optional,
> Tuple,
> + cast,
> )
>
> from docutils import nodes
>
> -from sphinx.addnodes import pending_xref
> +from sphinx.addnodes import desc_signature, pending_xref
> +from sphinx.directives import ObjectDescription
> from sphinx.domains import (
> Domain,
> Index,
> @@ -28,7 +30,7 @@
> from sphinx.locale import _, __
> from sphinx.roles import XRefRole
> from sphinx.util import logging
> -from sphinx.util.nodes import make_refnode
> +from sphinx.util.nodes import make_id, make_refnode
>
>
> if TYPE_CHECKING:
> @@ -96,6 +98,65 @@ def process_link(
> return title, target
>
>
> +Signature = str
> +
> +
> +class QAPIDescription(ObjectDescription[Signature]):
> + """
> + Generic QAPI description.
> +
> + Abstract class, not instantiated directly.
> + """
> +
> + def handle_signature(self, sig: str, signode: desc_signature) ->
> Signature:
> + # Do nothing. The return value here is the "name" of the entity
> + # being documented; for QAPI, this is the same as the
> + # "signature", which is just a name.
> +
> + # Normally this method must also populate signode with nodes to
> + # render the signature; here we do nothing instead.
> + return sig
> +
> + def get_index_text(self, name: Signature) -> Tuple[str, str]:
> + """Return the text for the index entry of the object."""
> +
> + # NB: this is used for the global index, not the QAPI index.
> + return ("single", f"{name} (QMP {self.objtype})")
> +
> + def add_target_and_index(
> + self, name: Signature, sig: str, signode: desc_signature
> + ) -> None:
> + # name is the return value of handle_signature.
> + # sig is the original, raw text argument to handle_signature.
> + # For QAPI, these are identical, currently.
> +
> + 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
> +
> + node_id = make_id(self.env, self.state.document, self.objtype,
> fullname)
pycodestyle-3 points out:
docs/sphinx/qapi_domain.py:144:80: E501 line too long (80 > 79 characters)
> + signode["ids"].append(node_id)
> +
> + self.state.document.note_explicit_target(signode)
> + domain = cast(QAPIDomain, self.env.get_domain("qapi"))
> + domain.note_object(fullname, self.objtype, node_id, location=signode)
This one's pushing it, too :)
> +
> + if "no-index-entry" not in self.options:
> + arity, indextext = self.get_index_text(name)
> + assert self.indexnode is not None
> + if indextext:
> + self.indexnode["entries"].append(
> + (arity, indextext, node_id, "", None)
> + )
> +
> +
> class QAPIIndex(Index):
> """
> Index subclass to provide the QAPI definition index.
