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]
> + ObjectDescription.option_spec.copy()
> + )
> + option_spec.update(
> + {
> + # Borrowed from the Python domain:
This is line 125 mentioned above.
> + "module": directives.unchanged, # Override contextual module
> name
> + }
> + )
[...]
