[Frontend] Only show the summary line of config docstrings in --help (#57357)
Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com> Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5
parent
8be3ca35f3
commit
0ef8366ba3
@@ -524,3 +524,20 @@ def test_flat_product():
|
|||||||
(3, 4, "a", 5, 6),
|
(3, 4, "a", 5, 6),
|
||||||
(3, 4, "b", 5, 6),
|
(3, 4, "b", 5, 6),
|
||||||
]
|
]
|
||||||
|
|
||||||
|
|
||||||
|
def test_group_description_is_summary_only():
|
||||||
|
"""Group descriptions are config docstrings, too long for the terminal."""
|
||||||
|
parser = FlexibleArgumentParser()
|
||||||
|
group = parser.add_argument_group(
|
||||||
|
title="MyConfig",
|
||||||
|
description="Summary line.\n\nDetails which only belong in the docs.",
|
||||||
|
)
|
||||||
|
group.add_argument("--my-arg")
|
||||||
|
|
||||||
|
assert "Summary line." in parser.format_help()
|
||||||
|
assert "only belong in the docs" not in parser.format_help()
|
||||||
|
|
||||||
|
parser._search_keyword = "myconfig"
|
||||||
|
assert "Summary line." in parser.format_help()
|
||||||
|
assert "only belong in the docs" not in parser.format_help()
|
||||||
|
|||||||
@@ -93,6 +93,11 @@ def human_readable_int_or_auto(value: str) -> int:
|
|||||||
return human_readable_int(value)
|
return human_readable_int(value)
|
||||||
|
|
||||||
|
|
||||||
|
def summary_line(description: str | None) -> str:
|
||||||
|
"""Return the first paragraph of a config docstring as a single line."""
|
||||||
|
return " ".join((description or "").split("\n\n", 1)[0].split())
|
||||||
|
|
||||||
|
|
||||||
class SortedHelpFormatter(ArgumentDefaultsHelpFormatter, RawDescriptionHelpFormatter):
|
class SortedHelpFormatter(ArgumentDefaultsHelpFormatter, RawDescriptionHelpFormatter):
|
||||||
"""SortedHelpFormatter that sorts arguments by their option strings."""
|
"""SortedHelpFormatter that sorts arguments by their option strings."""
|
||||||
|
|
||||||
@@ -203,7 +208,7 @@ class FlexibleArgumentParser(ArgumentParser):
|
|||||||
for group in self._action_groups:
|
for group in self._action_groups:
|
||||||
if group.title and group.title.lower() == search_keyword:
|
if group.title and group.title.lower() == search_keyword:
|
||||||
formatter.start_section(group.title)
|
formatter.start_section(group.title)
|
||||||
formatter.add_text(group.description)
|
formatter.add_text(summary_line(group.description))
|
||||||
formatter.add_arguments(group._group_actions)
|
formatter.add_arguments(group._group_actions)
|
||||||
formatter.end_section()
|
formatter.end_section()
|
||||||
formatter.add_text(self._json_tip)
|
formatter.add_text(self._json_tip)
|
||||||
@@ -242,12 +247,18 @@ class FlexibleArgumentParser(ArgumentParser):
|
|||||||
# positionals, optionals and user-defined groups
|
# positionals, optionals and user-defined groups
|
||||||
formatter.start_section("Config Groups")
|
formatter.start_section("Config Groups")
|
||||||
config_groups = ""
|
config_groups = ""
|
||||||
for group in self._action_groups:
|
groups = [g for g in self._action_groups if g._group_actions]
|
||||||
if not group._group_actions:
|
titles = [g.title or "" for g in groups]
|
||||||
continue
|
title_width = max((len(title) for title in titles), default=0) + 1
|
||||||
title = group.title
|
width = max(formatter._width - formatter._current_indent, title_width + 20)
|
||||||
description = group.description or ""
|
for title, group in zip(titles, groups):
|
||||||
config_groups += f"{title: <24}{description}\n"
|
lines = textwrap.wrap(
|
||||||
|
summary_line(group.description),
|
||||||
|
width,
|
||||||
|
initial_indent=f"{title: <{title_width}}",
|
||||||
|
subsequent_indent=" " * title_width,
|
||||||
|
)
|
||||||
|
config_groups += ("\n".join(lines) or title) + "\n"
|
||||||
formatter.add_text(config_groups)
|
formatter.add_text(config_groups)
|
||||||
formatter.end_section()
|
formatter.end_section()
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user