From b87eff8b7c06f5d104771561989f98ea7c809be5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Milo=C5=A1=20Prchl=C3=ADk?= <mprchlik@redhat.com>
Date: Fri, 18 Oct 2024 00:02:37 +0200
Subject: [PATCH] Improve CLI rendering of plugin docs (#3301)

* some paragraphs were glued together, that has been fixed by enforcing
  new line between top-level paragraphs,
* plugin's one-line "summary" and "description" were separated by one
  extra empty line, which is now gone.
---
 tmt/steps/__init__.py |  2 +-
 tmt/utils/rest.py     | 22 +++++++++++++++++-----
 2 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/tmt/steps/__init__.py b/tmt/steps/__init__.py
index 6d5d678964..14964a0adc 100644
--- a/tmt/steps/__init__.py
+++ b/tmt/steps/__init__.py
@@ -1179,7 +1179,7 @@ def __init__(
         lines = self.doc.splitlines()
 
         self.summary: str = lines[0].strip()
-        self.description: str = '\n'.join(lines[1:])
+        self.description: str = '\n'.join(lines[1:]).strip()
 
     def __repr__(self) -> str:
         return f'<{self.name} from {self.class_.__module__}>'
diff --git a/tmt/utils/rest.py b/tmt/utils/rest.py
index e57c6f39e4..6018b02f39 100644
--- a/tmt/utils/rest.py
+++ b/tmt/utils/rest.py
@@ -18,10 +18,11 @@
 from tmt.log import Logger
 from tmt.utils import GeneralError
 
+#: Special string representing a new-line in the stack of rendered
+#: paragraphs.
+NL = ''
+
 
-#
-# ReST rendering
-#
 class RestVisitor(docutils.nodes.NodeVisitor):
     """
     Custom renderer of docutils nodes.
@@ -63,6 +64,10 @@ def __init__(self, document: docutils.nodes.document, logger: Logger) -> None:
     def rendered(self) -> str:
         """ Return the rendered document as a single string """
 
+        # Drop any trailing empty lines
+        while self._rendered_paragraphs and self._rendered_paragraphs[-1] == NL:
+            self._rendered_paragraphs.pop(-1)
+
         return '\n'.join(self._rendered_paragraphs)
 
     def _emit(self, s: str) -> None:
@@ -91,8 +96,8 @@ def nl(self) -> None:
         # To simplify the implementation, this is merging of multiple
         # empty lines into one. Rendering of nodes than does not have
         # to worry about an empty line already being on the stack.
-        if self._rendered_paragraphs and self._rendered_paragraphs[-1] != '':
-            self._emit_paragraphs([''])
+        if self._rendered_paragraphs and self._rendered_paragraphs[-1] != NL:
+            self._emit_paragraphs([NL])
 
     # Simple logging for nodes that have no effect
     def _noop_visit(self, node: docutils.nodes.Node) -> None:
@@ -131,6 +136,13 @@ def visit_paragraph(self, node: docutils.nodes.paragraph) -> None:
     def depart_paragraph(self, node: docutils.nodes.paragraph) -> None:
         self.log_departure(str(node))
 
+        # Top-level paragraphs should be followed by an empty line to
+        # prevent paragraphs sticking together. Only the top-level ones
+        # though, we do not want empty lines after every paragraph-like
+        # string, because a lot of nodes are also paragraphs.
+        if isinstance(node.parent, docutils.nodes.document):
+            self.nl()
+
         self.flush()
 
     def visit_Text(self, node: docutils.nodes.Text) -> None:  # noqa: N802