remote/client: sphinx autoprogram workarounds

Hide intentionally undocumented subcommands and overlong lists of
choices.

Work around shortcomings of autoprogram's subcommand handling:

 - Don't show the --help, -h option for each subparser
 - Display aliases as `command subcommand|alias --option`
 - Show the "help" message of the subparser

Signed-off-by: Jonas Rebmann <jre@pengutronix.de>

Author: jonrebm

labgrid/remote/client.py

@@ -1708,8 +1708,35 @@ def __str__(self):
         return self.value
 
 
-def get_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser()
+def get_parser(include_undocumented=False) -> argparse.ArgumentParser:
+
+    # A fixed-width formatter to make usage string formatting predictable for manpage generation
+    def formatter(prog):
+        return argparse.HelpFormatter(prog, width=(None if include_undocumented else 180))
+
+    parser = argparse.ArgumentParser(add_help=include_undocumented, formatter_class=formatter)
+
+    # if the parser is requested for manpage generation, inject some workarounds for subcommands
+    if not include_undocumented:
+        argparse_add_parser = argparse._SubParsersAction.add_parser
+
+        def man_add_parser(self, name, **kwargs):
+            # hide --help,-h
+            kwargs.setdefault("add_help", False)
+            # aliases are not supported by autoprogram, they lead to duplicate entries
+            # instead, show them as `command subcommand|alias --option`
+            aliases = kwargs.pop("aliases", [])
+            if aliases:
+                name = "|".join([name] + list(aliases))
+            # the "help" message is ignore by autoprogram. Use "description" instead.
+            if "description" not in kwargs and "help" in kwargs:
+                kwargs["description"] = kwargs.pop("help")
+            # make usage string formatting predictable
+            kwargs["formatter_class"] = formatter
+            return argparse_add_parser(self, name, **kwargs)
+
+        argparse._SubParsersAction.add_parser = man_add_parser
+
     parser.add_argument(
         "-x",
         "--coordinator",
@@ -1747,11 +1774,12 @@ def get_parser() -> argparse.ArgumentParser:
         metavar="COMMAND",
     )
 
-    subparser = subparsers.add_parser("help")
+    if include_undocumented:
+        subparser = subparsers.add_parser("help")
 
-    subparser = subparsers.add_parser("complete")
-    subparser.add_argument("type", choices=["resources", "places", "matches", "match-names"])
-    subparser.set_defaults(func=ClientSession.complete)
+        subparser = subparsers.add_parser("complete")
+        subparser.add_argument("type", choices=["resources", "places", "matches", "match-names"])
+        subparser.set_defaults(func=ClientSession.complete)
 
     subparser = subparsers.add_parser("monitor", help="monitor events from the coordinator")
     subparser.set_defaults(func=ClientSession.do_monitor)
@@ -2000,7 +2028,7 @@ def get_parser() -> argparse.ArgumentParser:
         "-p",
         "--partition",
         type=int,
-        choices=range(0, 256),
+        choices=(range(0, 256) if include_undocumented else None),
         metavar="0-255",
         default=1,
         help="partition number to mount or 0 to mount whole disk (default: %(default)s)",
@@ -2094,7 +2122,7 @@ def main():
     initial_state = os.environ.get("LG_INITIAL_STATE", None)
     token = os.environ.get("LG_TOKEN", None)
 
-    parser = get_parser()
+    parser = get_parser(include_undocumented=True)
 
     # make any leftover arguments available for some commands
     args, leftover = parser.parse_known_args()