[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:
Harry Mellor
2026-09-17 12:53:11 +00:00
committed by GitHub
co-authored by Claude Opus 5
parent 8be3ca35f3
commit 0ef8366ba3
2 changed files with 35 additions and 7 deletions
+17
View File
@@ -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()
+18 -7
View File
@@ -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()