docs/qapi: enable new guest-agent and storage-daemon docs

[PATCH 04/11] docs/qapi-domain: add :namespace: override option

Posted by John Snow 8 months, 1 week ago

Akin to the :module: override option, the :namespace: options allows you
to forcibly override the contextual namespace associatied with a
definition.

We don't necessarily actually need this, but I felt compelled to stick
close to how the Python domain works that offers context overrides.

As of this commit, it is possible to add e.g. ":namespace: QMP" to any
QAPI directive to forcibly associate that definition with a given
namespace.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 docs/devel/qapi-domain.rst | 2 ++
 docs/sphinx/qapi_domain.py | 5 +++--
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/docs/devel/qapi-domain.rst b/docs/devel/qapi-domain.rst
index 1475870ca6c..51b283277e1 100644
--- a/docs/devel/qapi-domain.rst
+++ b/docs/devel/qapi-domain.rst
@@ -466,6 +466,8 @@ QAPI standard options
 
 All QAPI directives -- *except* for module -- support these common options.
 
+* ``:namespace: name`` -- This option allows you to override the
+  namespace association of a given definition.
 * ``:module: modname`` -- Borrowed from the Python domain, this option allows
   you to override the module association of a given definition.
 * ``:since: x.y`` -- Allows the documenting of "Since" information, which is
diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py
index 48a082d489a..6485c432063 100644
--- a/docs/sphinx/qapi_domain.py
+++ b/docs/sphinx/qapi_domain.py
@@ -294,8 +294,9 @@ class QAPIObject(QAPIDescription):
     )
     option_spec.update(
         {
-            # Borrowed from the Python domain:
-            "module": directives.unchanged,  # Override contextual module name
+            # Context overrides:
+            "namespace": directives.unchanged,
+            "module": directives.unchanged,
             # These are QAPI originals:
             "since": directives.unchanged,
             "ifcond": directives.unchanged,
-- 
2.48.1

Re: [PATCH 04/11] docs/qapi-domain: add :namespace: override option

Posted by Markus Armbruster 8 months, 1 week ago

John Snow <jsnow@redhat.com> writes:

> Akin to the :module: override option, the :namespace: options allows you
> to forcibly override the contextual namespace associatied with a
> definition.
>
> We don't necessarily actually need this, but I felt compelled to stick
> close to how the Python domain works that offers context overrides.
>
> As of this commit, it is possible to add e.g. ":namespace: QMP" to any
> QAPI directive to forcibly associate that definition with a given
> namespace.
>
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  docs/devel/qapi-domain.rst | 2 ++
>  docs/sphinx/qapi_domain.py | 5 +++--
>  2 files changed, 5 insertions(+), 2 deletions(-)
>
> diff --git a/docs/devel/qapi-domain.rst b/docs/devel/qapi-domain.rst
> index 1475870ca6c..51b283277e1 100644
> --- a/docs/devel/qapi-domain.rst
> +++ b/docs/devel/qapi-domain.rst
> @@ -466,6 +466,8 @@ QAPI standard options
>  
>  All QAPI directives -- *except* for module -- support these common options.
>  
> +* ``:namespace: name`` -- This option allows you to override the
> +  namespace association of a given definition.
>  * ``:module: modname`` -- Borrowed from the Python domain, this option allows
>    you to override the module association of a given definition.
>  * ``:since: x.y`` -- Allows the documenting of "Since" information, which is
> diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py
> index 48a082d489a..6485c432063 100644
> --- a/docs/sphinx/qapi_domain.py
> +++ b/docs/sphinx/qapi_domain.py
> @@ -294,8 +294,9 @@ class QAPIObject(QAPIDescription):
>      )
>      option_spec.update(
>          {
> -            # Borrowed from the Python domain:
> -            "module": directives.unchanged,  # Override contextual module name
> +            # Context overrides:
> +            "namespace": directives.unchanged,
> +            "module": directives.unchanged,
>              # These are QAPI originals:
>              "since": directives.unchanged,
>              "ifcond": directives.unchanged,

Did "Borrowed from the Python domain" become wrong(ish) in PATCH 02?

Re: [PATCH 04/11] docs/qapi-domain: add :namespace: override option

Posted by John Snow 8 months, 1 week ago

On Thu, Mar 13, 2025 at 2:39 AM Markus Armbruster <armbru@redhat.com> wrote:

> John Snow <jsnow@redhat.com> writes:
>
> > Akin to the :module: override option, the :namespace: options allows you
> > to forcibly override the contextual namespace associatied with a
> > definition.
> >
> > We don't necessarily actually need this, but I felt compelled to stick
> > close to how the Python domain works that offers context overrides.
> >
> > As of this commit, it is possible to add e.g. ":namespace: QMP" to any
> > QAPI directive to forcibly associate that definition with a given
> > namespace.
> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
> > ---
> >  docs/devel/qapi-domain.rst | 2 ++
> >  docs/sphinx/qapi_domain.py | 5 +++--
> >  2 files changed, 5 insertions(+), 2 deletions(-)
> >
> > diff --git a/docs/devel/qapi-domain.rst b/docs/devel/qapi-domain.rst
> > index 1475870ca6c..51b283277e1 100644
> > --- a/docs/devel/qapi-domain.rst
> > +++ b/docs/devel/qapi-domain.rst
> > @@ -466,6 +466,8 @@ QAPI standard options
> >
> >  All QAPI directives -- *except* for module -- support these common
> options.
> >
> > +* ``:namespace: name`` -- This option allows you to override the
> > +  namespace association of a given definition.
> >  * ``:module: modname`` -- Borrowed from the Python domain, this option
> allows
> >    you to override the module association of a given definition.
> >  * ``:since: x.y`` -- Allows the documenting of "Since" information,
> which is
> > diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py
> > index 48a082d489a..6485c432063 100644
> > --- a/docs/sphinx/qapi_domain.py
> > +++ b/docs/sphinx/qapi_domain.py
> > @@ -294,8 +294,9 @@ class QAPIObject(QAPIDescription):
> >      )
> >      option_spec.update(
> >          {
> > -            # Borrowed from the Python domain:
> > -            "module": directives.unchanged,  # Override contextual
> module name
> > +            # Context overrides:
> > +            "namespace": directives.unchanged,
> > +            "module": directives.unchanged,
> >              # These are QAPI originals:
> >              "since": directives.unchanged,
> >              "ifcond": directives.unchanged,
>
> Did "Borrowed from the Python domain" become wrong(ish) in PATCH 02?
>

:module: is directly borrowed, :namespace: is only spiritually similar.