🐛 fix: format option metavars with argparse's formatter

The option line assembled its own metavar text from dest and metavar: a
user metavar was upper-cased, nargs and choices were ignored, and a
positional with a tuple metavar showed only the first element. Usage on
the same page showed the correct spec, so the two disagreed.

Ask argparse's HelpFormatter._format_args for the text instead; it is the
same call that builds the usage line. Positionals join a tuple metavar
with spaces, as the name also serves as the reference anchor.

Author: gaborbernat

CHANGELOG.md

@@ -13,6 +13,8 @@ All notable changes to this project will be documented in this file.
   literals.
 - Make `:hook:` intercept `parse_intermixed_args()` as well as `parse_args()`.
 - Keep ANSI color codes out of usage blocks when `PYTHON_COLORS=1` is set on Python 3.14 or newer.
+- Render the argument spec after an option with argparse's formatter, so `nargs`, `choices` and tuple metavars show as
+  in the usage line; user-supplied metavars keep their case instead of being upper-cased.
 
 ## 1.13.1
 

roots/test-nargs-metavar/conf.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+extensions = ["sphinx_argparse_cli"]
+nitpicky = True

roots/test-nargs-metavar/index.rst

@@ -0,0 +1,3 @@
+.. sphinx_argparse_cli::
+  :module: parser
+  :func: make

roots/test-nargs-metavar/parser.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from argparse import REMAINDER, ArgumentParser
+
+
+def make() -> ArgumentParser:
+    parser = ArgumentParser(prog="tool", add_help=False)
+    parser.add_argument("--opt", nargs="?", help="optional value")
+    parser.add_argument("--many", nargs="*", help="zero or more")
+    parser.add_argument("--two", nargs=2, help="exactly two")
+    parser.add_argument("--rest", nargs=REMAINDER, help="the rest")
+    parser.add_argument("--out", metavar="<file>", help="output")
+    parser.add_argument("--dir", metavar="path/to/dir", help="dir")
+    parser.add_argument("--format", choices=["json", "xml"], help="output format")
+    parser.add_argument("pair", nargs=2, metavar=("SRC", "DST"), help="copy pair")
+    return parser

src/sphinx_argparse_cli/_logic.py

@@ -182,7 +182,7 @@ def run(self) -> list[Node]:
             if not group._group_actions or group is self.parser._subparsers:  # noqa: SLF001
                 continue
             home_section += self._mk_option_group(
-                group, prefix=self.parser.prog.split("/")[-1], prog=self.parser.prog.split("/")[-1]
+                self.parser, group, prefix=self.parser.prog.split("/")[-1], prog=self.parser.prog.split("/")[-1]
             )
         for aliases, help_msg, parser in self._iter_sub_commands():
             home_section += self._mk_sub_command(aliases, help_msg, parser)
@@ -206,7 +206,7 @@ def _pre_format(self, block: str | None) -> paragraph | literal_block | None:
         _protect_option_dashes(para)
         return para
 
-    def _mk_option_group(self, group: _ArgumentGroup, prefix: str, prog: str) -> section:
+    def _mk_option_group(self, parser: ArgumentParser, group: _ArgumentGroup, prefix: str, prog: str) -> section:
         sub_title_prefix: str = self.options.get("group_sub_title_prefix")
         title_prefix = self.options.get("group_title_prefix")
         title_text = self._build_opt_grp_title(group, prefix, prog, sub_title_prefix, title_prefix)
@@ -222,7 +222,7 @@ def _mk_option_group(self, group: _ArgumentGroup, prefix: str, prog: str) -> sec
         for action in group._group_actions:  # noqa: SLF001
             if action.help == SUPPRESS:
                 continue
-            point = self._mk_option_line(action, prefix)
+            point = self._mk_option_line(parser, action, prefix)
             opt_group += point
         group_section += opt_group
         return group_section
@@ -235,26 +235,22 @@ def _build_opt_grp_title(
         title_text += group.title or ""
         return title_text
 
-    def _mk_option_line(self, action: Action, prefix: str) -> list_item:
+    def _mk_option_line(self, parser: ArgumentParser, action: Action, prefix: str) -> list_item:
         line = paragraph()
-        as_key = action.dest
-        if action.metavar:
-            as_key = action.metavar if isinstance(action.metavar, str) else action.metavar[0]
         if action.option_strings:
+            args_text = _format_args(parser, action) if action.nargs != 0 else None
             for at, opt in enumerate(action.option_strings):
                 if at:
                     line += Text(", ")
                 self._mk_option_name(line, prefix, opt)
-                if action.nargs != 0:
+                if args_text is not None:
                     line += Text(" ")
-                    metavar_text = (
-                        " ".join(meta.upper() for meta in action.metavar)
-                        if isinstance(action.metavar, tuple)
-                        else as_key.upper()
-                    )
-                    line += literal(text=metavar_text)
+                    line += literal(text=args_text)
         else:
-            self._mk_option_name(line, prefix, as_key)
+            metavar = action.metavar
+            self._mk_option_name(
+                line, prefix, " ".join(metavar) if isinstance(metavar, tuple) else metavar or action.dest
+            )
 
         if action.help:
             help_text = load_help_text(action.help)
@@ -347,7 +343,9 @@ def _mk_sub_command(self, aliases: list[str], help_msg: str, parser: ArgumentPar
                 continue
             if isinstance(group._group_actions[0], _SubParsersAction):  # noqa: SLF001
                 continue
-            group_section += self._mk_option_group(group, prefix=parser.prog, prog=self.parser.prog.split("/")[-1])
+            group_section += self._mk_option_group(
+                parser, group, prefix=parser.prog, prog=self.parser.prog.split("/")[-1]
+            )
         return group_section
 
     def _build_sub_cmd_title(self, parser: ArgumentParser, sub_title_prefix: str, title_prefix: str) -> str:
@@ -404,6 +402,12 @@ def _no_color(self) -> Iterator[None]:
             yield
 
 
+def _format_args(parser: ArgumentParser, action: Action) -> str:
+    # argparse's formatter keeps the text in step with the usage line: nargs, choices and user metavars included
+    formatter = parser._get_formatter()  # noqa: SLF001
+    return formatter._format_args(action, formatter._get_default_metavar_for_optional(action))  # noqa: SLF001
+
+
 def make_id_lower(key: str) -> str:
     return re.sub("[A-Z]", lambda m: f"_{m.group(0).lower()}", make_id(key))
 

tests/complex.txt

@@ -16,7 +16,7 @@ complex options
 
 * **"--no-help"**
 
-* **"--outdir"** "OUT_DIR", **"-o"** "OUT_DIR" - output directory
+* **"--outdir"** "out_dir", **"-o"** "out_dir" - output directory
 
 * **"--in-dir"** "IN_DIR", **"-i"** "IN_DIR" - input directory
 

tests/complex_pre_310.txt

@@ -16,7 +16,7 @@ complex optional arguments
 
 * **"--no-help"**
 
-* **"--outdir"** "OUT_DIR", **"-o"** "OUT_DIR" - output directory
+* **"--outdir"** "out_dir", **"-o"** "out_dir" - output directory
 
 * **"--in-dir"** "IN_DIR", **"-i"** "IN_DIR" - input directory
 

tests/test_logic.py

@@ -486,6 +486,44 @@ def test_nargs(build_outcome: str) -> None:
     assert 'default: "None"' not in build_outcome
 
 
+@pytest.mark.sphinx(buildername="text", testroot="nargs-metavar")
+def test_nargs_metavar(build_outcome: str) -> None:
+    assert (
+        build_outcome
+        == """tool - CLI interface
+********************
+
+   tool [--opt [OPT]] [--many [MANY ...]] [--two TWO TWO] [--rest ...] [--out <file>]
+        [--dir path/to/dir] [--format {json,xml}]
+        SRC DST
+
+
+tool positional arguments
+=========================
+
+* **"SRC DST"** - copy pair
+
+
+tool options
+============
+
+* **"--opt"** "[OPT]" - optional value
+
+* **"--many"** "[MANY ...]" - zero or more
+
+* **"--two"** "TWO TWO" - exactly two
+
+* **"--rest"** "..." - the rest
+
+* **"--out"** "<file>" - output
+
+* **"--dir"** "path/to/dir" - dir
+
+* **"--format"** "{json,xml}" - output format
+"""
+    )
+
+
 @pytest.mark.sphinx(buildername="text", testroot="choices")
 def test_choices(build_outcome: str) -> None:
     assert "output format" in build_outcome