1. Patchew
  2. QEMU
  3. [PATCH v2 00/62] docs: Add new QAPI transmogrifier
  4. View patch

[PATCH v2 43/62] docs/qapidoc: add preamble() method

John Snow posted 62 patches 3 weeks, 4 days ago
There is a newer version of this series
[PATCH v2 43/62] docs/qapidoc: add preamble() method
Posted by John Snow 3 weeks, 4 days ago 
This method adds the options/preamble to each definition block. Notably,
:since: and :ifcond: are added, as are any "special features" such as
:deprecated: and :unstable:.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 docs/sphinx/qapidoc.py | 41 ++++++++++++++++++++++++++++++++++++++---
 1 file changed, 38 insertions(+), 3 deletions(-)

diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index cf5dbb0133d..d8bf0073dfa 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -37,7 +37,12 @@
 from docutils.parsers.rst import Directive, directives
 from docutils.statemachine import StringList
 from qapi.error import QAPIError
-from qapi.schema import QAPISchema, QAPISchemaVisitor
+from qapi.parser import QAPIDoc
+from qapi.schema import (
+    QAPISchema,
+    QAPISchemaDefinition,
+    QAPISchemaVisitor,
+)
 from qapi.source import QAPISourceInfo
 
 from qapidoc_legacy import QAPISchemaGenRSTVisitor  # type: ignore
@@ -56,8 +61,6 @@
         Sequence,
     )
 
-    from qapi.parser import QAPIDoc
-
     from sphinx.application import Sphinx
     from sphinx.util.typing import ExtensionMetadata
 
@@ -125,6 +128,38 @@ def ensure_blank_line(self) -> None:
             # +2: correct for zero/one index, then increment by one.
             self.add_line_raw("", fname, line + 2)
 
+    # Transmogrification helpers
+
+    def preamble(self, ent: QAPISchemaDefinition) -> None:
+        """
+        Generate option lines for qapi entity directives.
+        """
+        if ent.doc and ent.doc.since:
+            assert ent.doc.since.kind == QAPIDoc.Kind.SINCE
+            # Generated from the entity's docblock; info location is exact.
+            self.add_line(f":since: {ent.doc.since.text}", ent.doc.since.info)
+
+        if ent.ifcond.is_present():
+            doc = ent.ifcond.docgen()
+            assert ent.info
+            # Generated from entity definition; info location is approximate.
+            self.add_line(f":ifcond: {doc}", ent.info)
+
+        # Hoist special features such as :deprecated: and :unstable:
+        # into the options block for the entity. If, in the future, new
+        # special features are added, qapi-domain will chirp about
+        # unrecognized options and fail until they are handled in
+        # qapi-domain.
+        for feat in ent.features:
+            if feat.is_special():
+                # FIXME: handle ifcond if present. How to display that
+                # information is TBD.
+                # Generated from entity def; info location is approximate.
+                assert feat.info
+                self.add_line(f":{feat.name}:", feat.info)
+
+        self.ensure_blank_line()
+
     # Transmogrification core methods
 
     def visit_module(self, path: str) -> None:
-- 
2.48.1
Re: [PATCH v2 43/62] docs/qapidoc: add preamble() method
Posted by Markus Armbruster 3 weeks, 3 days ago 
John Snow <jsnow@redhat.com> writes:

> This method adds the options/preamble to each definition block. Notably,
> :since: and :ifcond: are added, as are any "special features" such as
> :deprecated: and :unstable:.
>
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  docs/sphinx/qapidoc.py | 41 ++++++++++++++++++++++++++++++++++++++---
>  1 file changed, 38 insertions(+), 3 deletions(-)
>
> diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
> index cf5dbb0133d..d8bf0073dfa 100644
> --- a/docs/sphinx/qapidoc.py
> +++ b/docs/sphinx/qapidoc.py
> @@ -37,7 +37,12 @@
>  from docutils.parsers.rst import Directive, directives
>  from docutils.statemachine import StringList
>  from qapi.error import QAPIError
> -from qapi.schema import QAPISchema, QAPISchemaVisitor
> +from qapi.parser import QAPIDoc
> +from qapi.schema import (
> +    QAPISchema,
> +    QAPISchemaDefinition,
> +    QAPISchemaVisitor,
> +)
>  from qapi.source import QAPISourceInfo
>  
>  from qapidoc_legacy import QAPISchemaGenRSTVisitor  # type: ignore
> @@ -56,8 +61,6 @@
>          Sequence,
>      )
>  
> -    from qapi.parser import QAPIDoc
> -
>      from sphinx.application import Sphinx
>      from sphinx.util.typing import ExtensionMetadata
>  
> @@ -125,6 +128,38 @@ def ensure_blank_line(self) -> None:
>              # +2: correct for zero/one index, then increment by one.
>              self.add_line_raw("", fname, line + 2)
>  
> +    # Transmogrification helpers
> +
> +    def preamble(self, ent: QAPISchemaDefinition) -> None:
> +        """
> +        Generate option lines for qapi entity directives.

QAPI index unless there's a reason for lower case.

> +        """

[...]
Re: [PATCH v2 43/62] docs/qapidoc: add preamble() method
Posted by Markus Armbruster 3 weeks, 2 days ago 
Markus Armbruster <armbru@redhat.com> writes:

> John Snow <jsnow@redhat.com> writes:
>
>> This method adds the options/preamble to each definition block. Notably,
>> :since: and :ifcond: are added, as are any "special features" such as
>> :deprecated: and :unstable:.
>>
>> Signed-off-by: John Snow <jsnow@redhat.com>
>> ---
>>  docs/sphinx/qapidoc.py | 41 ++++++++++++++++++++++++++++++++++++++---
>>  1 file changed, 38 insertions(+), 3 deletions(-)
>>
>> diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
>> index cf5dbb0133d..d8bf0073dfa 100644
>> --- a/docs/sphinx/qapidoc.py
>> +++ b/docs/sphinx/qapidoc.py
>> @@ -37,7 +37,12 @@
>>  from docutils.parsers.rst import Directive, directives
>>  from docutils.statemachine import StringList
>>  from qapi.error import QAPIError
>> -from qapi.schema import QAPISchema, QAPISchemaVisitor
>> +from qapi.parser import QAPIDoc
>> +from qapi.schema import (
>> +    QAPISchema,
>> +    QAPISchemaDefinition,
>> +    QAPISchemaVisitor,
>> +)
>>  from qapi.source import QAPISourceInfo
>>  
>>  from qapidoc_legacy import QAPISchemaGenRSTVisitor  # type: ignore
>> @@ -56,8 +61,6 @@
>>          Sequence,
>>      )
>>  
>> -    from qapi.parser import QAPIDoc
>> -
>>      from sphinx.application import Sphinx
>>      from sphinx.util.typing import ExtensionMetadata
>>  
>> @@ -125,6 +128,38 @@ def ensure_blank_line(self) -> None:
>>              # +2: correct for zero/one index, then increment by one.
>>              self.add_line_raw("", fname, line + 2)
>>  
>> +    # Transmogrification helpers
>> +
>> +    def preamble(self, ent: QAPISchemaDefinition) -> None:
>> +        """
>> +        Generate option lines for qapi entity directives.
>
> QAPI index unless there's a reason for lower case.

Pasto; I mean QAPI entity, of course.

>> +        """
>
> [...]
Re: [PATCH v2 43/62] docs/qapidoc: add preamble() method
Posted by Markus Armbruster 3 weeks, 3 days ago 
John Snow <jsnow@redhat.com> writes:

> This method adds the options/preamble to each definition block. Notably,
> :since: and :ifcond: are added, as are any "special features" such as
> :deprecated: and :unstable:.
>
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  docs/sphinx/qapidoc.py | 41 ++++++++++++++++++++++++++++++++++++++---
>  1 file changed, 38 insertions(+), 3 deletions(-)
>
> diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
> index cf5dbb0133d..d8bf0073dfa 100644
> --- a/docs/sphinx/qapidoc.py
> +++ b/docs/sphinx/qapidoc.py
> @@ -37,7 +37,12 @@
>  from docutils.parsers.rst import Directive, directives
>  from docutils.statemachine import StringList
>  from qapi.error import QAPIError
> -from qapi.schema import QAPISchema, QAPISchemaVisitor
> +from qapi.parser import QAPIDoc
> +from qapi.schema import (
> +    QAPISchema,
> +    QAPISchemaDefinition,
> +    QAPISchemaVisitor,
> +)
>  from qapi.source import QAPISourceInfo
>  
>  from qapidoc_legacy import QAPISchemaGenRSTVisitor  # type: ignore
> @@ -56,8 +61,6 @@
>          Sequence,
>      )
>  
> -    from qapi.parser import QAPIDoc
> -

Accident?

>      from sphinx.application import Sphinx
>      from sphinx.util.typing import ExtensionMetadata
>  
> @@ -125,6 +128,38 @@ def ensure_blank_line(self) -> None:
>              # +2: correct for zero/one index, then increment by one.
>              self.add_line_raw("", fname, line + 2)
>  
> +    # Transmogrification helpers
> +
> +    def preamble(self, ent: QAPISchemaDefinition) -> None:
> +        """
> +        Generate option lines for qapi entity directives.
> +        """
> +        if ent.doc and ent.doc.since:
> +            assert ent.doc.since.kind == QAPIDoc.Kind.SINCE
> +            # Generated from the entity's docblock; info location is exact.
> +            self.add_line(f":since: {ent.doc.since.text}", ent.doc.since.info)

Break the line aftee the comma?

> +
> +        if ent.ifcond.is_present():
> +            doc = ent.ifcond.docgen()
> +            assert ent.info
> +            # Generated from entity definition; info location is approximate.
> +            self.add_line(f":ifcond: {doc}", ent.info)
> +
> +        # Hoist special features such as :deprecated: and :unstable:
> +        # into the options block for the entity. If, in the future, new
> +        # special features are added, qapi-domain will chirp about
> +        # unrecognized options and fail until they are handled in
> +        # qapi-domain.
> +        for feat in ent.features:
> +            if feat.is_special():
> +                # FIXME: handle ifcond if present. How to display that

If I remember correctly, you wanted to mention this FIXME in the commit
message.

> +                # information is TBD.
> +                # Generated from entity def; info location is approximate.
> +                assert feat.info
> +                self.add_line(f":{feat.name}:", feat.info)
> +
> +        self.ensure_blank_line()
> +
>      # Transmogrification core methods
>  
>      def visit_module(self, path: str) -> None:
Re: [PATCH v2 43/62] docs/qapidoc: add preamble() method
Posted by John Snow 3 weeks, 2 days ago 
On Sun, Mar 9, 2025 at 5:03 PM Markus Armbruster <armbru@redhat.com> wrote:

> John Snow <jsnow@redhat.com> writes:
>
> > This method adds the options/preamble to each definition block. Notably,
> > :since: and :ifcond: are added, as are any "special features" such as
> > :deprecated: and :unstable:.
> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
> > ---
> >  docs/sphinx/qapidoc.py | 41 ++++++++++++++++++++++++++++++++++++++---
> >  1 file changed, 38 insertions(+), 3 deletions(-)
> >
> > diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
> > index cf5dbb0133d..d8bf0073dfa 100644
> > --- a/docs/sphinx/qapidoc.py
> > +++ b/docs/sphinx/qapidoc.py
> > @@ -37,7 +37,12 @@
> >  from docutils.parsers.rst import Directive, directives
> >  from docutils.statemachine import StringList
> >  from qapi.error import QAPIError
> > -from qapi.schema import QAPISchema, QAPISchemaVisitor
> > +from qapi.parser import QAPIDoc
> > +from qapi.schema import (
> > +    QAPISchema,
> > +    QAPISchemaDefinition,
> > +    QAPISchemaVisitor,
> > +)
> >  from qapi.source import QAPISourceInfo
> >
> >  from qapidoc_legacy import QAPISchemaGenRSTVisitor  # type: ignore
> > @@ -56,8 +61,6 @@
> >          Sequence,
> >      )
> >
> > -    from qapi.parser import QAPIDoc
> > -
>
> Accident?
>

I don't know. isort decided to move it and none of my tooling complains
about it.


>
> >      from sphinx.application import Sphinx
> >      from sphinx.util.typing import ExtensionMetadata
> >
> > @@ -125,6 +128,38 @@ def ensure_blank_line(self) -> None:
> >              # +2: correct for zero/one index, then increment by one.
> >              self.add_line_raw("", fname, line + 2)
> >
> > +    # Transmogrification helpers
> > +
> > +    def preamble(self, ent: QAPISchemaDefinition) -> None:
> > +        """
> > +        Generate option lines for qapi entity directives.
> > +        """
> > +        if ent.doc and ent.doc.since:
> > +            assert ent.doc.since.kind == QAPIDoc.Kind.SINCE
> > +            # Generated from the entity's docblock; info location is
> exact.
> > +            self.add_line(f":since: {ent.doc.since.text}",
> ent.doc.since.info)
>
> Break the line aftee the comma?
>
> > +
> > +        if ent.ifcond.is_present():
> > +            doc = ent.ifcond.docgen()
> > +            assert ent.info
> > +            # Generated from entity definition; info location is
> approximate.
> > +            self.add_line(f":ifcond: {doc}", ent.info)
> > +
> > +        # Hoist special features such as :deprecated: and :unstable:
> > +        # into the options block for the entity. If, in the future, new
> > +        # special features are added, qapi-domain will chirp about
> > +        # unrecognized options and fail until they are handled in
> > +        # qapi-domain.
> > +        for feat in ent.features:
> > +            if feat.is_special():
> > +                # FIXME: handle ifcond if present. How to display that
>
> If I remember correctly, you wanted to mention this FIXME in the commit
> message.
>
> > +                # information is TBD.
> > +                # Generated from entity def; info location is
> approximate.
> > +                assert feat.info
> > +                self.add_line(f":{feat.name}:", feat.info)
> > +
> > +        self.ensure_blank_line()
> > +
> >      # Transmogrification core methods
> >
> >      def visit_module(self, path: str) -> None:
>
>
Re: [PATCH v2 43/62] docs/qapidoc: add preamble() method
Posted by John Snow 3 weeks, 2 days ago 
On Mon, Mar 10, 2025 at 5:05 PM John Snow <jsnow@redhat.com> wrote:

>
>
> On Sun, Mar 9, 2025 at 5:03 PM Markus Armbruster <armbru@redhat.com>
> wrote:
>
>> John Snow <jsnow@redhat.com> writes:
>>
>> > This method adds the options/preamble to each definition block. Notably,
>> > :since: and :ifcond: are added, as are any "special features" such as
>> > :deprecated: and :unstable:.
>> >
>> > Signed-off-by: John Snow <jsnow@redhat.com>
>> > ---
>> >  docs/sphinx/qapidoc.py | 41 ++++++++++++++++++++++++++++++++++++++---
>> >  1 file changed, 38 insertions(+), 3 deletions(-)
>> >
>> > diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
>> > index cf5dbb0133d..d8bf0073dfa 100644
>> > --- a/docs/sphinx/qapidoc.py
>> > +++ b/docs/sphinx/qapidoc.py
>> > @@ -37,7 +37,12 @@
>> >  from docutils.parsers.rst import Directive, directives
>> >  from docutils.statemachine import StringList
>> >  from qapi.error import QAPIError
>> > -from qapi.schema import QAPISchema, QAPISchemaVisitor
>> > +from qapi.parser import QAPIDoc
>> > +from qapi.schema import (
>> > +    QAPISchema,
>> > +    QAPISchemaDefinition,
>> > +    QAPISchemaVisitor,
>> > +)
>> >  from qapi.source import QAPISourceInfo
>> >
>> >  from qapidoc_legacy import QAPISchemaGenRSTVisitor  # type: ignore
>> > @@ -56,8 +61,6 @@
>> >          Sequence,
>> >      )
>> >
>> > -    from qapi.parser import QAPIDoc
>> > -
>>
>> Accident?
>>
>
> I don't know. isort decided to move it and none of my tooling complains
> about it.
>

Ah, no, it's because it becomes used at runtime. Promoted from "type hint
only".

--js


>
>
>>
>> >      from sphinx.application import Sphinx
>> >      from sphinx.util.typing import ExtensionMetadata
>> >
>> > @@ -125,6 +128,38 @@ def ensure_blank_line(self) -> None:
>> >              # +2: correct for zero/one index, then increment by one.
>> >              self.add_line_raw("", fname, line + 2)
>> >
>> > +    # Transmogrification helpers
>> > +
>> > +    def preamble(self, ent: QAPISchemaDefinition) -> None:
>> > +        """
>> > +        Generate option lines for qapi entity directives.
>> > +        """
>> > +        if ent.doc and ent.doc.since:
>> > +            assert ent.doc.since.kind == QAPIDoc.Kind.SINCE
>> > +            # Generated from the entity's docblock; info location is
>> exact.
>> > +            self.add_line(f":since: {ent.doc.since.text}",
>> ent.doc.since.info)
>>
>> Break the line aftee the comma?
>>
>> > +
>> > +        if ent.ifcond.is_present():
>> > +            doc = ent.ifcond.docgen()
>> > +            assert ent.info
>> > +            # Generated from entity definition; info location is
>> approximate.
>> > +            self.add_line(f":ifcond: {doc}", ent.info)
>> > +
>> > +        # Hoist special features such as :deprecated: and :unstable:
>> > +        # into the options block for the entity. If, in the future, new
>> > +        # special features are added, qapi-domain will chirp about
>> > +        # unrecognized options and fail until they are handled in
>> > +        # qapi-domain.
>> > +        for feat in ent.features:
>> > +            if feat.is_special():
>> > +                # FIXME: handle ifcond if present. How to display that
>>
>> If I remember correctly, you wanted to mention this FIXME in the commit
>> message.
>>
>> > +                # information is TBD.
>> > +                # Generated from entity def; info location is
>> approximate.
>> > +                assert feat.info
>> > +                self.add_line(f":{feat.name}:", feat.info)
>> > +
>> > +        self.ensure_blank_line()
>> > +
>> >      # Transmogrification core methods
>> >
>> >      def visit_module(self, path: str) -> None:
>>
>>

Patchew 2.1-devel-b67e4c2

© 2016 - 2025 Red Hat, Inc.