pmaint eclass: improve rst output

Signed-off-by: Arthur Zamarin <arthurzam@gentoo.org>

3 files changed, 50 insertions, 32 deletions

diff --git a/src/pkgcore/ebuild/eclass.py b/src/pkgcore/ebuild/eclass.py
index f5ae214f7..23e970f75 100644
--- a/src/pkgcore/ebuild/eclass.py
+++ b/src/pkgcore/ebuild/eclass.py
@@ -118,17 +118,23 @@ class ParseEclassDoc:
             return None
 
         # use literal blocks for all multiline text
-        data = ["::", "\n\n"]
+        data = ["\n\n"]
 
+        inside_code = False
         for i, line in enumerate(lines, 1):
             if self._code_tag.match(line):
-                continue
+                if not inside_code:
+                    data.append("::")
+                data.append("\n\n")
+                inside_code = not inside_code
             elif mo := self._subsection_tag.match(line):
                 header = _rst_header("~", mo.group("title"))
                 data.extend(f"{x}\n" for x in header)
-                data.extend(["::", "\n\n"])
+                data.extend(["\n\n"])
             elif line:
-                data.append(f"  {line}\n")
+                indent = "  " if inside_code else ""
+                formatted_line = line
+                data.append(f"{indent}{formatted_line}\n")
             else:
                 data.append("\n")
 
@@ -572,7 +578,9 @@ class EclassDoc(AttrDict):
 
         rst = _header_only("=", self.name, leading=True)
         if self.blurb:
-            rst.extend(_header_only("-", self.blurb, leading=True))
+            rst.extend(_rst_header("-", "Name"))
+            rst.append(f"``{self.name}`` -- {self.blurb}")
+            rst.append("")
 
         if self.description:
             rst.extend(_rst_header("-", "Description"))
@@ -592,7 +600,7 @@ class EclassDoc(AttrDict):
             rst.append("")
         if self.raw_provides:
             rst.extend(_rst_header("-", "Transitively Provided Eclasses"))
-            rst.append(" ".join(self.raw_provides))
+            rst.extend(f"- ``{provide}``" for provide in self.raw_provides)
             rst.append("")
         if self.example:
             rst.extend(_rst_header("-", "Example"))
@@ -616,22 +624,25 @@ class EclassDoc(AttrDict):
                 header = [func.name]
                 if func.usage:
                     header.append(func.usage)
-                rst.extend(_rst_header("~", " ".join(header)))
+                rst.append(f'**{" ".join(header)}**')
                 if func.description:
-                    rst.append(func.description)
+                    rst.append(
+                        "  " + func.description.lstrip("\n").replace("\n", "\n  ")
+                    )
                 if func.returns:
                     if func.description:
-                        rst.append("")
-                    rst.append(f"Return value: {func.returns}")
+                        rst.append("  ")
+                    rst.append(f"  **Return value**: {func.returns}")
                 rst.append("")
         if external_vars := [x for x in self.variables if not x.internal]:
             rst.extend(_header_only("-", "Variables"))
             for var in external_vars:
                 vartype = ""
+                var_value = ""
                 if default_value := getattr(var, "default_value", None):
-                    vartype += f" ?= *{default_value}*"
+                    var_value = f" ?= *{default_value}*"
                 elif initial_value := getattr(var, "initial_value", None):
-                    vartype += f" = *{initial_value}*"
+                    var_value = f" = *{initial_value}*"
                 if var.required:
                     vartype += " (REQUIRED)"
                 if var.pre_inherit:
@@ -639,11 +650,12 @@ class EclassDoc(AttrDict):
                 if var.user_variable:
                     vartype += " (USER VARIABLE)"
                 if var.output_variable:
-                    vartype += " (OUTPUT VARIABLE)"
-
-                rst.extend(_rst_header("~", var.name + vartype))
+                    vartype += " (GENERATED BY ECLASS)"
+                rst.append(f"**{var.name}**{var_value}{vartype}")
                 if var.description:
-                    rst.append(var.description)
+                    rst.append(
+                        "  " + var.description.lstrip("\n").replace("\n", "\n  ")
+                    )
                 rst.append("")
         if external_func_vars := [x for x in self.function_variables if not x.internal]:
             rst.extend(_header_only("-", "Function Variables"))
@@ -652,9 +664,11 @@ class EclassDoc(AttrDict):
                 if var.required:
                     vartype += " (REQUIRED)"
 
-                rst.extend(_rst_header("~", var.name + vartype))
+                rst.append(f"**{var.name}**{vartype}")
                 if var.description:
-                    rst.append(var.description)
+                    rst.append(
+                        "  " + var.description.lstrip("\n").replace("\n", "\n  ")
+                    )
                 rst.append("")
 
         if self.authors:
@@ -711,6 +725,7 @@ class EclassDoc(AttrDict):
                 super().__init__(*args, **kwargs)
                 self._docinfo.update(man_data)
 
+        self.blurb = None  # skip addition of blurb as man page header already holds it
         writer = manpage.Writer()
         writer.translator_class = Translator
         return self._to_docutils(writer)
diff --git a/src/pkgcore/scripts/pmaint.py b/src/pkgcore/scripts/pmaint.py
index 9c92f655e..008de533f 100644
--- a/src/pkgcore/scripts/pmaint.py
+++ b/src/pkgcore/scripts/pmaint.py
@@ -547,6 +547,9 @@ def _eclass_main(options, out, err):
                 obj = EclassDoc(path, sourced=True)
                 convert_func = getattr(obj, f"to_{options.format}")
                 f.write(convert_func())
+        except NotImplementedError as e:
+            err.write(f"{eclass.prog}: failed {path!r}: {e}")
+            raise
         except ValueError as e:
             # skip eclasses lacking eclassdoc support
             err.write(f"{eclass.prog}: skipping {path!r}: {e}")
diff --git a/tests/ebuild/test_eclass.py b/tests/ebuild/test_eclass.py
index 045261f39..1d71d81ec 100644
--- a/tests/ebuild/test_eclass.py
+++ b/tests/ebuild/test_eclass.py
@@ -123,16 +123,16 @@ class TestEclassDoc:
             "Random Person <maintainer@random.email>",
         )
         assert doc.description == (
-            "::\n\n"
-            "  Yadda yadda yadda.\n"
-            "  Lots to say here.\n\n"
-            "  Really, very interesting eclass.\n\n"
+            "\n\n"
+            "Yadda yadda yadda.\n"
+            "Lots to say here.\n\n"
+            "Really, very interesting eclass.\n\n"
             "How to use it\n"
-            "~~~~~~~~~~~~~\n"
-            "::\n\n"
-            "  Somehow."
+            "~~~~~~~~~~~~~\n\n\n"
+            "Somehow."
         )
         assert doc.example == (
+            "\n\n"
             "::\n\n"
             "  inherit foo\n\n"
             "  src_prepare() {\n"
@@ -166,7 +166,7 @@ class TestEclassDoc:
             "deprecated": False,
             "internal": True,
             "maintainers": ("Some Person <someone@random.email>",),
-            "description": "::\n\n  Internal stub function.",
+            "description": "\n\nInternal stub function.",
             "usage": "<bar> [<baz>]",
         }
 
@@ -176,7 +176,7 @@ class TestEclassDoc:
             "deprecated": "bar_public_func",
             "internal": False,
             "maintainers": None,
-            "description": "::\n\n  Public stub function.",
+            "description": "\n\nPublic stub function.",
             "usage": None,
         }
 
@@ -187,7 +187,7 @@ class TestEclassDoc:
             "default_unset": True,
             "internal": True,
             "required": False,
-            "description": "::\n\n  Internal variable for foo_public_func.",
+            "description": "\n\nInternal variable for foo_public_func.",
         }
         assert doc.function_variables[1] == {
             "name": "FOO_PUBLIC_VAR",
@@ -195,7 +195,7 @@ class TestEclassDoc:
             "default_unset": False,
             "internal": False,
             "required": True,
-            "description": "::\n\n  Public variable for foo_public_func.",
+            "description": "\n\nPublic variable for foo_public_func.",
         }
 
         assert len(doc.variables) == 3
@@ -208,7 +208,7 @@ class TestEclassDoc:
             "pre_inherit": False,
             "user_variable": False,
             "output_variable": False,
-            "description": "::\n\n  Internal variable.",
+            "description": "\n\nInternal variable.",
         }
         assert doc.variables[1] == {
             "name": "FOO_PUBLIC_ECLASS_VAR",
@@ -219,7 +219,7 @@ class TestEclassDoc:
             "pre_inherit": True,
             "user_variable": False,
             "output_variable": False,
-            "description": "::\n\n  Public variable.",
+            "description": "\n\nPublic variable.",
         }
         assert doc.variables[2] == {
             "name": "FOO_ANOTHER_ECLASS_VAR",
@@ -230,7 +230,7 @@ class TestEclassDoc:
             "pre_inherit": False,
             "user_variable": False,
             "output_variable": False,
-            "description": "::\n\n  Yet another variable.",
+            "description": "\n\nYet another variable.",
         }
 
     def test_recursive_provides(self, tmp_path):