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

[Markus Armbruster <armbru@redhat.com>]

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?

>          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.

>          # Squelch empty paragraphs.
>          if not section.text:
>              return
>  
> +        dedent = bool(section.kind == QAPIDoc.Kind.INTRO)
>          self.ensure_blank_line()
> -        self.add_lines(section.text, section.info)
> +        self.add_lines(section.text, section.info, dedent)
>          self.ensure_blank_line()
>  
>      def visit_member(self, section: QAPIDoc.ArgSection) -> None:
> @@ -367,7 +375,7 @@ def visit_sections(self, ent: QAPISchemaDefinition) -> None:
>              section.text = self.reformat_arobase(section.text)
>  
>              if section.kind.name in ("PLAIN", "INTRO"):
> -                self.visit_paragraph(section)
> +                self.visit_text(section)
>              elif section.kind == QAPIDoc.Kind.MEMBER:
>                  assert isinstance(section, QAPIDoc.ArgSection)
>                  if section.name == "q_dummy":