On Fri, Mar 7, 2025 at 1:34 AM Markus Armbruster <arm...@redhat.com> wrote:
> John Snow <js...@redhat.com> writes:
>
> > This commit adds a stubbed version of QAPICommand that utilizes the
> > QAPIObject class, the qapi:command directive, the :qapi:cmd:
> > cross-reference role, and the "command" object type in the QAPI object
> > registry.
> >
> > This commit also adds the aforementioned generic QAPIObject class for
> > use in documenting various QAPI entities in the Sphinx ecosystem.
> >
> > They don't do anything *particularly* interesting yet, but that will
> > come in forthcoming commits.
> >
> > Note: some versions of mypy get a little confused over the difference
> > between class and instance variables; because sphinx's ObjectDescription
> > does not declare option_spec as a ClassVar (even though it's obvious
> > that it is), mypy may produce this error:
> >
> > qapi-domain.py:125: error: Cannot override instance variable (previously
> > declared on base class "ObjectDescription") with class variable [misc]
> >
> > I can't control that; so silence the error with a pragma.
>
> Is this still accurate? qapi-domain.py line 125 is a comment. I can't
> see the pragma.
>
> > Signed-off-by: John Snow <js...@redhat.com>
> > ---
> > docs/sphinx/qapi_domain.py | 146 ++++++++++++++++++++++++++++++++++++-
> > 1 file changed, 144 insertions(+), 2 deletions(-)
> >
> > diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py
> > index 104bae709f3..6168c23936f 100644
> > --- a/docs/sphinx/qapi_domain.py
> > +++ b/docs/sphinx/qapi_domain.py
> > @@ -21,9 +21,10 @@
> > from docutils import nodes
> > from docutils.parsers.rst import directives
> >
> > -from compat import nested_parse
> > +from compat import KeywordNode, SpaceNode, nested_parse
> > from sphinx import addnodes
> > -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,
> > @@ -103,6 +104,144 @@ 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
> > +
> > +
> > +class QAPIObject(ObjectDescription[Signature]):
> > + """
> > + 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]
>
Originally, that pointed here.
> > + ObjectDescription.option_spec.copy()
> > + )
> > + option_spec.update(
> > + {
> > + # Borrowed from the Python domain:
>
> This is line 125 mentioned above.
>
Slightly stale.
>
> > + "module": directives.unchanged, # Override contextual
> module name
> > + }
> > + )
>
> [...]
>
>
