From 0ef8366ba39fc38b88c60b17ee2ddf05aa8a7596 Mon Sep 17 00:00:00 2001 From: Harry Mellor <19981378+hmellor@users.noreply.github.com> Date: Thu, 17 Sep 2026 13:53:11 +0100 Subject: [PATCH] [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) --- tests/utils_/test_argparse_utils.py | 17 +++++++++++++++++ vllm/utils/argparse_utils.py | 25 ++++++++++++++++++------- 2 files changed, 35 insertions(+), 7 deletions(-) diff --git a/tests/utils_/test_argparse_utils.py b/tests/utils_/test_argparse_utils.py index baf57d994f..89e0f9977d 100644 --- a/tests/utils_/test_argparse_utils.py +++ b/tests/utils_/test_argparse_utils.py @@ -524,3 +524,20 @@ def test_flat_product(): (3, 4, "a", 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() diff --git a/vllm/utils/argparse_utils.py b/vllm/utils/argparse_utils.py index e573cbc293..d214da3402 100644 --- a/vllm/utils/argparse_utils.py +++ b/vllm/utils/argparse_utils.py @@ -93,6 +93,11 @@ def human_readable_int_or_auto(value: str) -> int: 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): """SortedHelpFormatter that sorts arguments by their option strings.""" @@ -203,7 +208,7 @@ class FlexibleArgumentParser(ArgumentParser): for group in self._action_groups: if group.title and group.title.lower() == search_keyword: formatter.start_section(group.title) - formatter.add_text(group.description) + formatter.add_text(summary_line(group.description)) formatter.add_arguments(group._group_actions) formatter.end_section() formatter.add_text(self._json_tip) @@ -242,12 +247,18 @@ class FlexibleArgumentParser(ArgumentParser): # positionals, optionals and user-defined groups formatter.start_section("Config Groups") config_groups = "" - for group in self._action_groups: - if not group._group_actions: - continue - title = group.title - description = group.description or "" - config_groups += f"{title: <24}{description}\n" + groups = [g for g in self._action_groups if g._group_actions] + titles = [g.title or "" for g in groups] + title_width = max((len(title) for title in titles), default=0) + 1 + width = max(formatter._width - formatter._current_indent, title_width + 20) + for title, group in zip(titles, groups): + 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.end_section()