Re: [PATCH v2 08/13] qapi/docs: Add rendering for INTRO sections

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> On Mon, May 4, 2026 at 8:05 AM Markus Armbruster <armbru@redhat.com> wrote:
>>
>> John Snow <jsnow@redhat.com> writes:
>>
>> > The only real difference here is that we need to dedent all but the
>> > first line so that it renders correctly. We don't need to do this for
>> > members and features because they are always rendered as part of a field
>> > list directive which expects indented lines - Undecorated plaintext
>> > doesn't, so we chop the indent off.
>> >
>> > This does not reflow the text or mess with the source info in any way,
>> > so "blame" for error messages should be unchanged.
>> >
>> > Signed-off-by: John Snow <jsnow@redhat.com>
>> > ---
>> >  docs/sphinx/qapidoc.py | 14 +++++++++++---
>> >  1 file changed, 11 insertions(+), 3 deletions(-)
>> >
>> > diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
>> > index 70ab9cdc214..6b8e4ecd76a 100644
>> > --- a/docs/sphinx/qapidoc.py
>> > +++ b/docs/sphinx/qapidoc.py
>> > @@ -35,6 +35,7 @@
>> >  from pathlib import Path
>> >  import re
>> >  import sys
>> > +import textwrap
>> >  from typing import TYPE_CHECKING
>> >
>> >  from docutils import nodes
>> > @@ -150,8 +151,14 @@ def add_lines(
>> >          self,
>> >          content: str,
>> >          info: QAPISourceInfo,
>> > +        dedent: bool = False,
>> >      ) -> None:
>> >          lines = content.splitlines(True)
>> > +
>> > +        if dedent:
>> > +            txt = "".join(lines[1:])
>> > +            lines[1:] = textwrap.dedent(txt).splitlines(True)
>> > +
>>
>> Sure you want to wrap and not just remove indentation?
>
> "textwrap" is the module, "dedent" is the function. This really is
> just removing indentation. It just happens to be bundled with the
> "textwrap" stdlib module.

Basic reading comprehension fail, my apologies.

>> >          for i, line in enumerate(lines):
>> >              self.add_line_raw(line, info.fname, info.line + i)
>> >
>> > @@ -223,13 +230,14 @@ def reformat_arobase(text: str) -> str:
>> >
>> >      # Transmogrification helpers
>> >
>> > -    def visit_paragraph(self, section: QAPIDoc.Section) -> None:
>> > +    def visit_text(self, section: QAPIDoc.Section) -> None:
>>
>> This is what gets used for sections of kind PLAIN and INTRO.  Can we
>> come up with a better term for these than "text"?  Your turf, so I
>> *will* take no for an answer.
>
> "patches welcome" - I was just avoiding the use of "paragraph" for
> something that might be multiple paragraphs.

Could use "paragraphs".

>                                              Once the literal "PLAIN"
> section is removed (in favor of semantic successors INTRO and
> DETAILS), we can use "visit_plaintext" to refer to the general
> category, but currently it's semantically overloaded.
>
> How about I just do "visit_plaintext" and we suffer with the slight
> ambiguity for the interim? not married to "text", "plaintext" or
> anything else, just don't have better ideas and naming is one of the
> two hard problems in CS.

The temporary ambiguity feels tolerable.

"plaintext" is probably clearer than "paragraphs" once it's no longer
ambiguous.

Thanks!