Skip to content

Commit

Permalink
pmaint eclass: improve rst output
Browse files Browse the repository at this point in the history 
Signed-off-by: Arthur Zamarin <arthurzam@gentoo.org>
  • Loading branch information
@arthurzam
arthurzam committed Oct 23, 2023
1 parent 388e86d commit 83516bb
Show file tree
Hide file tree
Showing 3 changed files with 50 additions and 32 deletions.
51 changes: 33 additions & 18 deletions src/pkgcore/ebuild/eclass.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -118,17 +118,23 @@ def _tag_multiline_str(self, block, tag, lineno):
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")

Expand Down Expand Up @@ -572,7 +578,9 @@ def to_rst(self):

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"))
Expand All @@ -592,7 +600,7 @@ def to_rst(self):
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"))
Expand All @@ -616,34 +624,38 @@ def to_rst(self):
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:
vartype += " (SET BEFORE INHERIT)"
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"))
Expand All @@ -652,9 +664,11 @@ def to_rst(self):
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:
Expand Down Expand Up @@ -711,6 +725,7 @@ def __init__(self, *args, **kwargs):
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)
Expand Down
3 changes: 3 additions & 0 deletions src/pkgcore/scripts/pmaint.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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}")
Expand Down
28 changes: 14 additions & 14 deletions tests/ebuild/test_eclass.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -123,16 +123,16 @@ def test_foo_eclass(self, tmp_path):
"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"
Expand Down Expand Up @@ -166,7 +166,7 @@ def test_foo_eclass(self, tmp_path):
"deprecated": False,
"internal": True,
"maintainers": ("Some Person <someone@random.email>",),
"description": "::\n\n Internal stub function.",
"description": "\n\nInternal stub function.",
"usage": "<bar> [<baz>]",
}

Expand All @@ -176,7 +176,7 @@ def test_foo_eclass(self, tmp_path):
"deprecated": "bar_public_func",
"internal": False,
"maintainers": None,
"description": "::\n\n Public stub function.",
"description": "\n\nPublic stub function.",
"usage": None,
}

Expand All @@ -187,15 +187,15 @@ def test_foo_eclass(self, tmp_path):
"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",
"deprecated": "BAR_PUBLIC_VAR",
"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
Expand All @@ -208,7 +208,7 @@ def test_foo_eclass(self, tmp_path):
"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",
Expand All @@ -219,7 +219,7 @@ def test_foo_eclass(self, tmp_path):
"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",
Expand All @@ -230,7 +230,7 @@ def test_foo_eclass(self, tmp_path):
"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):
Expand Down

0 comments on commit 83516bb

Please sign in to comment.