Notably, this method does not currently address the formatting issues
present with the "errors" section in QAPIDoc and just vomits the text
verbatim into the rST doc, with somewhat inconsistent results.

To be addressed in a future revision.

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

diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index b96445f0802..14feafe866e 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -139,6 +139,12 @@ def visit_paragraph(self, section: QAPIDoc.Section) -> None:
         self.add_lines(section.text, section.info)
         self.ensure_blank_line()
 
+    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)
+
     def preamble(self, ent: QAPISchemaDefinition) -> None:
         """
         Generate option lines for qapi entity directives.
-- 
2.48.1

John Snow <jsnow@redhat.com> writes:

> Notably, this method does not currently address the formatting issues
> present with the "errors" section in QAPIDoc and just vomits the text
> verbatim into the rST doc, with somewhat inconsistent results.
>
> To be addressed in a future revision.
>
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  docs/sphinx/qapidoc.py | 6 ++++++
>  1 file changed, 6 insertions(+)
>
> diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
> index b96445f0802..14feafe866e 100644
> --- a/docs/sphinx/qapidoc.py
> +++ b/docs/sphinx/qapidoc.py
> @@ -139,6 +139,12 @@ def visit_paragraph(self, section: QAPIDoc.Section) -> None:
>          self.add_lines(section.text, section.info)
>          self.ensure_blank_line()
>  
> +    def visit_errors(self, section: QAPIDoc.Section) -> None:
> +        # FIXME: the formatting for errors may be inconsistent and may

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

> +        # 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)
> +
>      def preamble(self, ent: QAPISchemaDefinition) -> None:
>          """
>          Generate option lines for qapi entity directives.

On Sun, Mar 9, 2025 at 5:05 PM Markus Armbruster <armbru@redhat.com> wrote:

> John Snow <jsnow@redhat.com> writes:
>
> > Notably, this method does not currently address the formatting issues
> > present with the "errors" section in QAPIDoc and just vomits the text
> > verbatim into the rST doc, with somewhat inconsistent results.
> >
> > To be addressed in a future revision.
> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
> > ---
> >  docs/sphinx/qapidoc.py | 6 ++++++
> >  1 file changed, 6 insertions(+)
> >
> > diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
> > index b96445f0802..14feafe866e 100644
> > --- a/docs/sphinx/qapidoc.py
> > +++ b/docs/sphinx/qapidoc.py
> > @@ -139,6 +139,12 @@ def visit_paragraph(self, section: QAPIDoc.Section)
> -> None:
> >          self.add_lines(section.text, section.info)
> >          self.ensure_blank_line()
> >
> > +    def visit_errors(self, section: QAPIDoc.Section) -> None:
> > +        # FIXME: the formatting for errors may be inconsistent and may
>
> If I remember correctly, you wanted to mention this FIXME in the commit
> message.
>

Well, that's what the entire commit message is already about! Both of these
places are talking about the visual misalignment and enforcing the source
formatting of errors to fix the visual alignment problems.


>
> > +        # 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)
> > +
> >      def preamble(self, ent: QAPISchemaDefinition) -> None:
> >          """
> >          Generate option lines for qapi entity directives.
>
>

John Snow <jsnow@redhat.com> writes:

> On Sun, Mar 9, 2025 at 5:05 PM Markus Armbruster <armbru@redhat.com> wrote:
>
>> John Snow <jsnow@redhat.com> writes:
>>
>> > Notably, this method does not currently address the formatting issues
>> > present with the "errors" section in QAPIDoc and just vomits the text
>> > verbatim into the rST doc, with somewhat inconsistent results.
>> >
>> > To be addressed in a future revision.
>> >
>> > Signed-off-by: John Snow <jsnow@redhat.com>
>> > ---
>> >  docs/sphinx/qapidoc.py | 6 ++++++
>> >  1 file changed, 6 insertions(+)
>> >
>> > diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
>> > index b96445f0802..14feafe866e 100644
>> > --- a/docs/sphinx/qapidoc.py
>> > +++ b/docs/sphinx/qapidoc.py
>> > @@ -139,6 +139,12 @@ def visit_paragraph(self, section: QAPIDoc.Section) -> None:
>> >          self.add_lines(section.text, section.info)
>> >          self.ensure_blank_line()
>> >
>> > +    def visit_errors(self, section: QAPIDoc.Section) -> None:
>> > +        # FIXME: the formatting for errors may be inconsistent and may
>>
>> If I remember correctly, you wanted to mention this FIXME in the commit
>> message.
>>
>
> Well, that's what the entire commit message is already about! Both of these
> places are talking about the visual misalignment and enforcing the source
> formatting of errors to fix the visual alignment problems.

Alright.  If the patch was larger, I'd ask you to replace

    To be addressed in a future revision.

by something like

    Marked FIXME in the code.

Both tell me there's something in need of fixing, but only the latter
tells me how to find the spot in need.

[...]