1. Patchew
  2. QEMU
  3. [PATCH v3 0/5] docs: remove legacy qapidoc
  4. View patch

[PATCH v3 2/5] docs/sphinx: parse @references in freeform text

John Snow posted 5 patches 4 months, 4 weeks ago
Maintainers: Markus Armbruster <armbru@redhat.com>, Michael Roth <michael.roth@amd.com>, "Philippe Mathieu-Daudé" <philmd@linaro.org>, "Daniel P. Berrangé" <berrange@redhat.com>, Kashyap Chamarthy <kchamart@redhat.com>, Kostiantyn Kostiuk <kkostiuk@redhat.com>, Kevin Wolf <kwolf@redhat.com>, "Michael S. Tsirkin" <mst@redhat.com>, Stefano Garzarella <sgarzare@redhat.com>, John Snow <jsnow@redhat.com>, Peter Maydell <peter.maydell@linaro.org>, Cleber Rosa <crosa@redhat.com>, Eric Blake <eblake@redhat.com>, Igor Mammedov <imammedo@redhat.com>, Ani Sinha <anisinha@redhat.com>, Gerd Hoffmann <kraxel@redhat.com>, "Marc-André Lureau" <marcandre.lureau@redhat.com>, Hanna Reitz <hreitz@redhat.com>, Paolo Bonzini <pbonzini@redhat.com>, "Gonglei (Arei)" <arei.gonglei@huawei.com>, Zhenwei Pi <pizhenwei@bytedance.com>, Jonathan Cameron <jonathan.cameron@huawei.com>, Fan Ni <fan.ni@samsung.com>, Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>, Eduardo Habkost <eduardo@habkost.net>, Marcel Apfelbaum <marcel.apfelbaum@gmail.com>, Yanan Wang <wangyanan55@huawei.com>, Zhao Liu <zhao1.liu@intel.com>, Peter Xu <peterx@redhat.com>, Fabiano Rosas <farosas@suse.de>, Jason Wang <jasowang@redhat.com>, "Alex Bennée" <alex.bennee@linaro.org>, Jiri Pirko <jiri@resnulli.us>, Stefan Berger <stefanb@linux.vnet.ibm.com>, Stefan Hajnoczi <stefanha@redhat.com>, Mads Ynddal <mads@ynddal.dk>, Alex Williamson <alex.williamson@redhat.com>, "Cédric Le Goater" <clg@redhat.com>, Lukas Straub <lukasstraub2@web.de>
[PATCH v3 2/5] docs/sphinx: parse @references in freeform text
Posted by John Snow 4 months, 4 weeks ago 
Oversight in the new qapidoc transmogrifier: @references in freeform
documentation blocks were not being transformed to literals. This fixes
that, and the next patch ensures that we're testing for this O:-)

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

diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 5374dee8fad..adc14ade456 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -218,6 +218,11 @@ def generate_field(
         typ = self.format_type(member)
         self.add_field(kind, member.name, body, info, typ)
 
+    @staticmethod
+    def reformat_arobase(text: str) -> str:
+        """ reformats @var to ``var`` """
+        return re.sub(r"@([\w-]+)", r"``\1``", text)
+
     # Transmogrification helpers
 
     def visit_paragraph(self, section: QAPIDoc.Section) -> None:
@@ -361,8 +366,7 @@ def visit_sections(self, ent: QAPISchemaDefinition) -> None:
 
         # Add sections in source order:
         for i, section in enumerate(sections):
-            # @var is translated to ``var``:
-            section.text = re.sub(r"@([\w-]+)", r"``\1``", section.text)
+            section.text = self.reformat_arobase(section.text)
 
             if section.kind == QAPIDoc.Kind.PLAIN:
                 self.visit_paragraph(section)
@@ -405,7 +409,7 @@ def visit_freeform(self, doc: QAPIDoc) -> None:
 
         assert len(doc.all_sections) == 1, doc.all_sections
         body = doc.all_sections[0]
-        text = body.text
+        text = self.reformat_arobase(body.text)
         info = doc.info
 
         if re.match(r"=+ ", text):
-- 
2.48.1
Re: [PATCH v3 2/5] docs/sphinx: parse @references in freeform text
Posted by Markus Armbruster 4 months, 3 weeks ago 
John Snow <jsnow@redhat.com> writes:

> Oversight in the new qapidoc transmogrifier: @references in freeform
> documentation blocks were not being transformed to literals. This fixes
> that, and the next patch ensures that we're testing for this O:-)
>
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  docs/sphinx/qapidoc.py | 10 +++++++---
>  1 file changed, 7 insertions(+), 3 deletions(-)
>
> diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
> index 5374dee8fad..adc14ade456 100644
> --- a/docs/sphinx/qapidoc.py
> +++ b/docs/sphinx/qapidoc.py
> @@ -218,6 +218,11 @@ def generate_field(
>          typ = self.format_type(member)
>          self.add_field(kind, member.name, body, info, typ)
>  
> +    @staticmethod
> +    def reformat_arobase(text: str) -> str:

What's an "arobase"?  Inquiring mind wants to know!

> +        """ reformats @var to ``var`` """
> +        return re.sub(r"@([\w-]+)", r"``\1``", text)
> +
>      # Transmogrification helpers
>  
>      def visit_paragraph(self, section: QAPIDoc.Section) -> None:
> @@ -361,8 +366,7 @@ def visit_sections(self, ent: QAPISchemaDefinition) -> None:
>  
>          # Add sections in source order:
>          for i, section in enumerate(sections):
> -            # @var is translated to ``var``:
> -            section.text = re.sub(r"@([\w-]+)", r"``\1``", section.text)
> +            section.text = self.reformat_arobase(section.text)
>  
>              if section.kind == QAPIDoc.Kind.PLAIN:
>                  self.visit_paragraph(section)
> @@ -405,7 +409,7 @@ def visit_freeform(self, doc: QAPIDoc) -> None:
>  
>          assert len(doc.all_sections) == 1, doc.all_sections
>          body = doc.all_sections[0]
> -        text = body.text
> +        text = self.reformat_arobase(body.text)
>          info = doc.info
>  
>          if re.match(r"=+ ", text):
Re: [PATCH v3 2/5] docs/sphinx: parse @references in freeform text
Posted by John Snow 4 months, 2 weeks ago 
On Fri, Jun 27, 2025, 5:54 AM Markus Armbruster <armbru@redhat.com> wrote:

> John Snow <jsnow@redhat.com> writes:
>
> > Oversight in the new qapidoc transmogrifier: @references in freeform
> > documentation blocks were not being transformed to literals. This fixes
> > that, and the next patch ensures that we're testing for this O:-)
> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
> > ---
> >  docs/sphinx/qapidoc.py | 10 +++++++---
> >  1 file changed, 7 insertions(+), 3 deletions(-)
> >
> > diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
> > index 5374dee8fad..adc14ade456 100644
> > --- a/docs/sphinx/qapidoc.py
> > +++ b/docs/sphinx/qapidoc.py
> > @@ -218,6 +218,11 @@ def generate_field(
> >          typ = self.format_type(member)
> >          self.add_field(kind, member.name, body, info, typ)
> >
> > +    @staticmethod
> > +    def reformat_arobase(text: str) -> str:
>
> What's an "arobase"?  Inquiring mind wants to know!
>

French for "at symbol thingie" :)

(Intentionally obtuse as an oblique joke, forgive my humor)


> > +        """ reformats @var to ``var`` """
> > +        return re.sub(r"@([\w-]+)", r"``\1``", text)
> > +
> >      # Transmogrification helpers
> >
> >      def visit_paragraph(self, section: QAPIDoc.Section) -> None:
> > @@ -361,8 +366,7 @@ def visit_sections(self, ent: QAPISchemaDefinition)
> -> None:
> >
> >          # Add sections in source order:
> >          for i, section in enumerate(sections):
> > -            # @var is translated to ``var``:
> > -            section.text = re.sub(r"@([\w-]+)", r"``\1``", section.text)
> > +            section.text = self.reformat_arobase(section.text)
> >
> >              if section.kind == QAPIDoc.Kind.PLAIN:
> >                  self.visit_paragraph(section)
> > @@ -405,7 +409,7 @@ def visit_freeform(self, doc: QAPIDoc) -> None:
> >
> >          assert len(doc.all_sections) == 1, doc.all_sections
> >          body = doc.all_sections[0]
> > -        text = body.text
> > +        text = self.reformat_arobase(body.text)
> >          info = doc.info
> >
> >          if re.match(r"=+ ", text):
>
>

Patchew 2.1-devel-b67e4c2

© 2016 - 2025 Red Hat, Inc.