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 <[email protected]> --- 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) + 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: # 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": -- 2.54.0
