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

[PATCH v3 1/5] docs/sphinx: adjust qapidoc to cope with same-line error sections

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 1/5] docs/sphinx: adjust qapidoc to cope with same-line error sections
Posted by John Snow 4 months, 4 weeks ago 
Signed-off-by: John Snow <jsnow@redhat.com>
---
 docs/sphinx/qapidoc.py | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 8011ac9efaf..5374dee8fad 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -267,10 +267,14 @@ def visit_returns(self, section: QAPIDoc.Section) -> None:
         self.add_field("return", typ, section.text, section.info)
 
     def visit_errors(self, section: QAPIDoc.Section) -> None:
-        # FIXME: the formatting for errors may be inconsistent and may
-        # or may not require different newline placement to ensure
-        # proper rendering as a nested list.
-        self.add_lines(f":error:\n{section.text}", section.info)
+        # If the section text does not start with a space, it means text
+        # began on the same line as the "Error:" string and we should
+        # not insert a newline in this case.
+        if section.text[0].isspace():
+            text = f":error:\n{section.text}"
+        else:
+            text = f":error: {section.text}"
+        self.add_lines(text, section.info)
 
     def preamble(self, ent: QAPISchemaDefinition) -> None:
         """
-- 
2.48.1
Re: [PATCH v3 1/5] docs/sphinx: adjust qapidoc to cope with same-line error sections
Posted by Markus Armbruster 4 months, 2 weeks ago 
John Snow <jsnow@redhat.com> writes:

> Signed-off-by: John Snow <jsnow@redhat.com>

Let's mention the reproducer: "# Errors: some" in doc-good.json with
:transmogrify:.

> ---
>  docs/sphinx/qapidoc.py | 12 ++++++++----
>  1 file changed, 8 insertions(+), 4 deletions(-)
>
> diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
> index 8011ac9efaf..5374dee8fad 100644
> --- a/docs/sphinx/qapidoc.py
> +++ b/docs/sphinx/qapidoc.py
> @@ -267,10 +267,14 @@ def visit_returns(self, section: QAPIDoc.Section) -> None:
>          self.add_field("return", typ, section.text, section.info)
>  
>      def visit_errors(self, section: QAPIDoc.Section) -> None:
> -        # FIXME: the formatting for errors may be inconsistent and may
> -        # or may not require different newline placement to ensure
> -        # proper rendering as a nested list.
> -        self.add_lines(f":error:\n{section.text}", section.info)
> +        # If the section text does not start with a space, it means text
> +        # began on the same line as the "Error:" string and we should
> +        # not insert a newline in this case.
> +        if section.text[0].isspace():
> +            text = f":error:\n{section.text}"
> +        else:
> +            text = f":error: {section.text}"
> +        self.add_lines(text, section.info)
>  
>      def preamble(self, ent: QAPISchemaDefinition) -> None:
>          """
Re: [PATCH v3 1/5] docs/sphinx: adjust qapidoc to cope with same-line error sections
Posted by Markus Armbruster 4 months ago 
Markus Armbruster <armbru@redhat.com> writes:

> John Snow <jsnow@redhat.com> writes:
>
>> Signed-off-by: John Snow <jsnow@redhat.com>
>
> Let's mention the reproducer: "# Errors: some" in doc-good.json with
> :transmogrify:.

I'm adding

    Without this, the line the new QAPI doc generator chokes on
    
        # Errors: some
    
    in doc-good.json.  We still use the old doc generator for the tests,
    but we're about to correct that.

and

    Fixes: e9fbf1a0c6c2 (docs/qapidoc: add visit_errors() method)

Patchew 2.1-devel-b67e4c2

© 2016 - 2025 Red Hat, Inc.