Prefer parser description over help message

Signed-off-by: Bernát Gábor <[email protected]>

Author: gaborbernat

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to this project will be documented in this file.
 
+## 1.5.1 (2021-04-15)
+
+- For sub-commands use the parser description first as description and only then fallback to the help message
+
 ## 1.5.0 (2021-02-13)
 
 - Display the metavar (fallback to dest) if the action has more than one argument (this is inline with how usage is

roots/test-complex/parser.py

@@ -21,7 +21,7 @@ def make() -> ArgumentParser:
     sub_parsers_a.required = False
     sub_parsers_a.default = "first"
 
-    a_parser_first = sub_parsers_a.add_parser("first", aliases=["f"], help="a-first-help")
+    a_parser_first = sub_parsers_a.add_parser("first", aliases=["f"], help="a-first-help", description="a-first-desc")
     a_parser_first.add_argument("--flag", dest="a_par_first_flag", action="store_true", help="a parser first flag")
     a_parser_first.add_argument("--root", action="store_true", help="root flag")
     a_parser_first.add_argument("pos_one", help="first positional argument", metavar="one")

src/sphinx_argparse_cli/_logic.py

@@ -186,8 +186,10 @@ def _mk_sub_command(self, aliases: list[str], help_msg: str, parser: ArgumentPar
         if aliases:
             title_text += f" ({', '.join(aliases)})"
         group_section = section("", title("", Text(title_text)), ids=[make_id(title_text)], names=[title_text])
-        if help_msg:
-            desc_paragraph = paragraph("", Text(help_msg))
+
+        command_desc = (parser.description or help_msg or "").strip()
+        if command_desc:
+            desc_paragraph = paragraph("", Text(command_desc))
             group_section += desc_paragraph
         group_section += self._mk_usage(parser)
         for group in parser._action_groups:  # noqa

tests/complex.txt

@@ -36,7 +36,7 @@ this is an exclusive group
 complex first (f)
 =================
 
-a-first-help
+a-first-desc
 
    complex first [-h] [--flag] [--root] one pos_two