feat(cli): add a custom help formatter

Add a custom argparse help formatter that overrides the output
format to list items vertically.

The formatter is derived from argparse.HelpFormatter with minimal changes.

Co-authored-by: John Villalovos <john@sodarock.com>
Co-authored-by: Nejc Habjan <nejc.habjan@siemens.com>

3 files changed, 33 insertions, 1 deletions

diff --git a/gitlab/cli.py b/gitlab/cli.py
index 9793964..fd519c3 100644
--- a/gitlab/cli.py
+++ b/gitlab/cli.py
@@ -50,6 +50,23 @@ custom_actions: Dict[str, Dict[str, Tuple[Tuple[str, ...], Tuple[str, ...], bool
 __F = TypeVar("__F", bound=Callable[..., Any])
 
 
+class VerticalHelpFormatter(argparse.HelpFormatter):
+    def format_help(self) -> str:
+        result = super().format_help()
+        output = ""
+        indent = self._indent_increment * " "
+        for line in result.splitlines(keepends=True):
+            # All of our resources are on one line and wrapped inside braces.
+            # For example: {application,resource1,resource2}
+            # We then put each resource on its own line to make it easier to read.
+            if line.strip().startswith("{"):
+                choices = line.strip().strip("{}").split(",")
+                choices_str = f"\n{indent}".join(choices)
+                line = f"{indent}{choices_str}\n"
+            output += line
+        return output
+
+
 def register_custom_action(
     cls_names: Union[str, Tuple[str, ...]],
     mandatory: Tuple[str, ...] = (),
@@ -110,6 +127,7 @@ def _get_base_parser(add_help: bool = True) -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         add_help=add_help,
         description="GitLab API Command Line Interface",
+        formatter_class=VerticalHelpFormatter,
         allow_abbrev=False,
     )
     parser.add_argument("--version", help="Display the version.", action="store_true")
diff --git a/gitlab/v4/cli.py b/gitlab/v4/cli.py
index 90b6ba6..48369f6 100644
--- a/gitlab/v4/cli.py
+++ b/gitlab/v4/cli.py
@@ -377,7 +377,9 @@ def extend_parser(parser: argparse.ArgumentParser) -> argparse.ArgumentParser:
 
     for cls in sorted(classes, key=operator.attrgetter("__name__")):
         arg_name = cli.cls_to_gitlab_resource(cls)
-        object_group = subparsers.add_parser(arg_name)
+        object_group = subparsers.add_parser(
+            arg_name, formatter_class=cli.VerticalHelpFormatter
+        )
 
         object_subparsers = object_group.add_subparsers(
             title="action",
diff --git a/tests/functional/cli/test_cli.py b/tests/functional/cli/test_cli.py
index f07fa2a..6edea7f 100644
--- a/tests/functional/cli/test_cli.py
+++ b/tests/functional/cli/test_cli.py
@@ -34,6 +34,18 @@ def test_config_error_with_help_prints_help(script_runner):
     assert ret.returncode == 0
 
 
+def test_global_help_prints_resources_vertically(script_runner):
+    ret = script_runner.run("gitlab", "--help")
+    assert """resource:\n  application\n  application-appearance\n""" in ret.stdout
+    assert ret.returncode == 0
+
+
+def test_resource_help_prints_actions_vertically(script_runner):
+    ret = script_runner.run("gitlab", "project", "--help")
+    assert """action:\n  list\n  get""" in ret.stdout
+    assert ret.returncode == 0
+
+
 @pytest.mark.script_launch_mode("inprocess")
 @responses.activate
 def test_defaults_to_gitlab_com(script_runner, resp_get_project, monkeypatch):