commit: 83516bb97445ef81c40c30a567703509fe29445b
Author: Arthur Zamarin <arthurzam <AT> gentoo <DOT> org>
AuthorDate: Mon Oct 23 17:03:30 2023 +0000
Commit: Arthur Zamarin <arthurzam <AT> gentoo <DOT> org>
CommitDate: Mon Oct 23 17:03:30 2023 +0000
URL:
https://gitweb.gentoo.org/proj/pkgcore/pkgcore.git/commit/?id=83516bb9
pmaint eclass: improve rst output
Signed-off-by: Arthur Zamarin <arthurzam <AT> gentoo.org>
src/pkgcore/ebuild/eclass.py | 51 ++++++++++++++++++++++++++++---------------
src/pkgcore/scripts/pmaint.py | 3 +++
tests/ebuild/test_eclass.py | 28 ++++++++++++------------
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):
