qapi: new sphinx qapi domain pre-requisites

[PATCH 18/20] qapi: ensure all errors sections are uniformly typset

John Snow posted 20 patches 6 months, 2 weeks ago

Download mbox

Maintainers: Markus Armbruster <armbru@redhat.com>, Michael Roth <michael.roth@amd.com>, Peter Maydell <peter.maydell@linaro.org>, Eric Blake <eblake@redhat.com>, "Michael S. Tsirkin" <mst@redhat.com>, Igor Mammedov <imammedo@redhat.com>, Ani Sinha <anisinha@redhat.com>, Gerd Hoffmann <kraxel@redhat.com>, "Marc-André Lureau" <marcandre.lureau@redhat.com>, Kevin Wolf <kwolf@redhat.com>, Hanna Reitz <hreitz@redhat.com>, Paolo Bonzini <pbonzini@redhat.com>, "Daniel P. Berrangé" <berrange@redhat.com>, Eduardo Habkost <eduardo@habkost.net>, Marcel Apfelbaum <marcel.apfelbaum@gmail.com>, "Philippe Mathieu-Daudé" <philmd@linaro.org>, Yanan Wang <wangyanan55@huawei.com>, Peter Xu <peterx@redhat.com>, Fabiano Rosas <farosas@suse.de>, Jason Wang <jasowang@redhat.com>, Pavel Dovgalyuk <pavel.dovgaluk@ispras.ru>, Jiri Pirko <jiri@resnulli.us>, Stefan Berger <stefanb@linux.vnet.ibm.com>, Stefan Hajnoczi <stefanha@redhat.com>, Mads Ynddal <mads@ynddal.dk>, Lukas Straub <lukasstraub2@web.de>, Konstantin Kostiuk <kkostiuk@redhat.com>

Expand all Fold all

[PATCH 18/20] qapi: ensure all errors sections are uniformly typset

Posted by John Snow 6 months, 2 weeks ago

Transactions have the only instance of an Errors section that isn't a
rST list; turn it into one.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qapi/transaction.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/qapi/transaction.json b/qapi/transaction.json
index 5749c133d4a..07afc269d54 100644
--- a/qapi/transaction.json
+++ b/qapi/transaction.json
@@ -235,7 +235,7 @@
 #     additional detail.
 #
 # Errors:
-#     Any errors from commands in the transaction
+#     - Any errors from commands in the transaction
 #
 # Note: The transaction aborts on the first failure.  Therefore, there
 #     will be information on only one failed operation returned in an
-- 
2.44.0

Re: [PATCH 18/20] qapi: ensure all errors sections are uniformly typset

Posted by Markus Armbruster 5 months, 1 week ago

John Snow <jsnow@redhat.com> writes:

> Transactions have the only instance of an Errors section that isn't a
> rST list; turn it into one.

Just for consistency?  Or do you have other shenanigans up your sleeve?

If we want the Errors sections to remain all rST lists, we should update
docs/devel/qapi-code-gen.rst to say so.

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

Re: [PATCH 18/20] qapi: ensure all errors sections are uniformly typset

Posted by John Snow 5 months, 1 week ago

On Fri, Jun 14, 2024, 7:24 AM Markus Armbruster <armbru@redhat.com> wrote:

> John Snow <jsnow@redhat.com> writes:
>
> > Transactions have the only instance of an Errors section that isn't a
> > rST list; turn it into one.
>
> Just for consistency?  Or do you have other shenanigans up your sleeve?
>

Just consistency at this precise moment in time, but it's *possible* I may
introduce shenanigans for visual consistency in the rendered output, for
which having a uniform format would make mechanical conversions in the
generator easier/possible.

It's an idea I had but didn't implement yet. I figured I'd write this patch
anyway because it isn't wrong, and you yourself seemed to believe it would
*always* be a RST list, when that isn't strictly true.

> If we want the Errors sections to remain all rST lists, we should update
> docs/devel/qapi-code-gen.rst to say so.
>

OK, will do.

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

Re: [PATCH 18/20] qapi: ensure all errors sections are uniformly typset

Posted by Markus Armbruster 5 months, 1 week ago

John Snow <jsnow@redhat.com> writes:

> On Fri, Jun 14, 2024, 7:24 AM Markus Armbruster <armbru@redhat.com> wrote:
>
>> John Snow <jsnow@redhat.com> writes:
>>
>> > Transactions have the only instance of an Errors section that isn't a
>> > rST list; turn it into one.
>>
>> Just for consistency?  Or do you have other shenanigans up your sleeve?
>
> Just consistency at this precise moment in time, but it's *possible* I may
> introduce shenanigans for visual consistency in the rendered output, for
> which having a uniform format would make mechanical conversions in the
> generator easier/possible.
>
> It's an idea I had but didn't implement yet. I figured I'd write this patch
> anyway because it isn't wrong, and you yourself seemed to believe it would
> *always* be a RST list, when that isn't strictly true.
>
>
>> If we want the Errors sections to remain all rST lists, we should update
>> docs/devel/qapi-code-gen.rst to say so.
>>
>
> OK, will do.

With such an update, we could perhaps sell the patch like

    qapi: Nail down convention that Errors sections are lists

    By unstated convention, Errors sections are rST lists.  Document the
    convention, and make the one exception conform.

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