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):