Improve the readability of CLI help page and table outputs (#604)

Author: yec-akamai

linodecli/__init__.py

@@ -10,7 +10,7 @@
 from sys import argv
 
 from rich import print as rprint
-from rich.table import Table
+from rich.table import Column, Table
 
 from linodecli import plugins
 
@@ -23,7 +23,14 @@
 from .cli import CLI
 from .completion import get_completions
 from .configuration import ENV_TOKEN_NAME
-from .help_pages import print_help_action, print_help_default
+from .help_pages import (
+    HELP_TOPICS,
+    print_help_action,
+    print_help_commands,
+    print_help_default,
+    print_help_env_vars,
+    print_help_plugins,
+)
 from .helpers import handle_url_overrides
 from .output import OutputMode
 from .version import __version__
@@ -154,7 +161,19 @@ def main():  # pylint: disable=too-many-branches,too-many-statements
     # handle a help for the CLI
     if parsed.command is None or (parsed.command is None and parsed.help):
         parser.print_help()
-        print_help_default(cli.ops, cli.config)
+        print_help_default()
+        sys.exit(0)
+
+    if parsed.command == "env-vars":
+        print_help_env_vars()
+        sys.exit(0)
+
+    if parsed.command == "commands":
+        print_help_commands(cli.ops)
+        sys.exit(0)
+
+    if parsed.command == "plugins":
+        print_help_plugins(cli.config)
         sys.exit(0)
 
     # configure
@@ -224,6 +243,7 @@ def main():  # pylint: disable=too-many-branches,too-many-statements
     if (
         parsed.command not in cli.ops
         and parsed.command not in plugins.available(cli.config)
+        and parsed.command not in HELP_TOPICS
     ):
         print(f"Unrecognized command {parsed.command}")
         sys.exit(1)
@@ -243,9 +263,13 @@ def main():  # pylint: disable=too-many-branches,too-many-statements
             for action, op in cli.ops[parsed.command].items()
         ]
 
-        table = Table("action", "summary")
+        table = Table(
+            Column(header="action", no_wrap=True),
+            Column(header="summary", style="cyan"),
+        )
         for row in content:
             table.add_row(*row)
+
         rprint(table)
         sys.exit(0)
 

linodecli/baked/colors.py

@@ -4,8 +4,6 @@
 
 from openapi3.paths import MediaType
 
-from .colors import colorize_string
-
 
 def _is_paginated(response):
     """
@@ -112,9 +110,9 @@ def _get_value(self, model):
 
     def render_value(self, model, colorize=True):
         """
-        Given the model returned from the API, returns the correctly- rendered
+        Given the model returned from the API, returns the correctly rendered
         version of it.  This can transform text based on various rules
-        configured in the spec using custom tags.  Currently supported tags:
+        configured in the spec using custom tags. Currently supported tags:
 
         x-linode-cli-color
           A list of key-value pairs that represent the value, and its ideal color.
@@ -125,10 +123,10 @@ def render_value(self, model, colorize=True):
         if isinstance(value, list):
             value = ", ".join([str(c) for c in value])
         if colorize and self.color_map is not None:
-            # Add color
+            # Add color using rich tags
             value = str(value)
             color = self.color_map.get(value) or self.color_map["default_"]
-            value = colorize_string(value, color)
+            value = f"[{color}]{value}[/]"
         if value is None:
             # Prints the word None if you don't change it
             value = ""

linodecli/baked/response.py

@@ -31,17 +31,22 @@
     "(e.g. 'https')",
 }
 
+HELP_TOPICS = {
+    "env-vars": "Environment variables that can be used",
+    "commands": "Learn about all available commands with linode-cli",
+    "plugins": " Learn about all available plugins registered to linode-cli",
+}
 
-# pylint: disable=too-many-locals
-def print_help_default(ops, config):
-    """
-    Prints help output with options from the API spec
+
+def print_help_env_vars():
     """
+    Print Environment variables overrides. Usage:
 
-    # Environment variables overrides
-    print("\nEnvironment variables:")
+        linode-cli env-vars
+    """
+    rprint("\n[bold cyan]Environment variables:")
 
-    table = Table(show_header=True, header_style="", box=box.SQUARE)
+    table = Table(show_header=True, header_style="bold", box=box.SQUARE)
     table.add_column("Name")
     table.add_column("Description")
 
@@ -50,32 +55,39 @@ def print_help_default(ops, config):
 
     rprint(table)
 
+
+def print_help_commands(ops):
+    """
+    Prints available commands. Usage:
+
+        linode-cli commands
+    """
     # commands to manage CLI users (don't call out to API)
-    print("\nCLI user management commands:")
+    rprint("\n[bold cyan]CLI user management commands:")
     um_commands = [["configure", "set-user", "show-users"], ["remove-user"]]
     table = Table(show_header=False)
     for cmd in um_commands:
         table.add_row(*cmd)
     rprint(table)
 
     # commands to manage plugins (don't call out to API)
-    print("\nCLI Plugin management commands:")
+    rprint("\n[bold cyan]CLI Plugin management commands:")
     pm_commands = [["register-plugin", "remove-plugin"]]
     table = Table(show_header=False)
     for cmd in pm_commands:
         table.add_row(*cmd)
     rprint(table)
 
     # other CLI commands
-    print("\nOther CLI commands:")
+    rprint("\n[bold cyan]Other CLI commands:")
     other_commands = [["completion"]]
     table = Table(show_header=False)
     for cmd in other_commands:
         table.add_row(*cmd)
     rprint(table)
 
     # commands generated from the spec (call the API directly)
-    print("\nAvailable commands:")
+    rprint("\n[bold cyan]Available commands:")
 
     content = list(sorted(ops.keys()))
     proc = []
@@ -89,10 +101,16 @@ def print_help_default(ops, config):
         table.add_row(*cmd)
     rprint(table)
 
-    # plugins registered to the CLI (do arbitrary things)
+
+def print_help_plugins(config):
+    """
+    Print available plugins registered to the CLI (do arbitrary things). Usage:
+
+        linode-cli plugins
+    """
     if plugins.available(config):
         # only show this if there are any available plugins
-        print("Available plugins:")
+        rprint("\n[bold cyan]Available plugins:")
 
         plugin_content = list(plugins.available(config))
         plugin_proc = []
@@ -107,7 +125,15 @@ def print_help_default(ops, config):
             plugin_table.add_row(*plugin)
         rprint(plugin_table)
 
-    print("\nTo reconfigure, call `linode-cli configure`")
+
+def print_help_default():
+    """
+    Prints help output with options from the API spec
+    """
+    rprint("\n[bold cyan]Help Topics")
+    for k, v in HELP_TOPICS.items():
+        print("  " + k + ": " + v)
+    rprint("\n[bold]To reconfigure[/], call `linode-cli configure`")
     print(
         "For comprehensive documentation, "
         "visit https://www.linode.com/docs/api/"
@@ -134,11 +160,11 @@ def print_help_action(
         console.print(f" [{pname}]", end="")
 
     console.print()
-    console.print(f"[bold]{op.summary}[/]")
+    console.print(f"[cyan]{op.summary}[/]")
 
     if op.docs_url:
         console.print(
-            f"[bold]API Documentation: [link={op.docs_url}]{op.docs_url}[/link][/]"
+            f"[bold]API Documentation[/]: [link={op.docs_url}]{op.docs_url}[/link]"
         )
 
     if len(op.samples) > 0:

linodecli/help_pages.py

@@ -12,7 +12,6 @@
 from rich import print as rprint
 from rich.console import OverflowMethod
 from rich.table import Column, Table
-from rich.text import Text
 
 from linodecli.baked.response import OpenAPIResponse, OpenAPIResponseAttr
 
@@ -288,13 +287,13 @@ def _table_output(
 
         tab = Table(
             *header_columns,
-            header_style="",
+            header_style="bold",
             box=box_style,
             show_header=self.headers,
             title_justify="left",
+            show_lines=True,
         )
         for row in content:
-            row = [Text.from_ansi(item) for item in row]
             tab.add_row(*row)
 
         if title is not None and self.headers:

linodecli/output.py

@@ -6,6 +6,8 @@
 
 from typing import Dict
 
+from rich import box
+from rich import print as rprint
 from rich.align import Align
 from rich.console import Console
 from rich.table import Table
@@ -65,7 +67,10 @@ def linode_types_with_region_prices(
     if len(json_data["data"]) < 1:
         return True
 
-    output = Table()
+    output = Table(
+        header_style="bold",
+        show_lines=True,
+    )
 
     # To ensure the order of the headers and make sure we have region_prices as the last column
     headers = sorted(
@@ -96,11 +101,11 @@ def linode_types_with_region_prices(
     console = Console()
     console.print(output)
 
-    print(
-        "See our [Pricing Page](https://www.linode.com/pricing/) for Region-specific pricing, "
-        + "which applies after migration is complete."
+    rprint(
+        "[cyan]See our [Pricing Page](https://www.linode.com/pricing/) "
+        "for Region-specific pricing, "
+        "which applies after migration is complete."
     )
-
     return False
 
 
@@ -119,7 +124,7 @@ def format_region_prices(data: Dict[str, any]) -> any:
     """
     subheaders = ["id", "hourly", "monthly"]
 
-    sub_table = Table()
+    sub_table = Table(box=box.SIMPLE_HEAVY)
 
     for header in subheaders:
         sub_table.add_column(header, justify="center")

linodecli/overrides.py

@@ -269,7 +269,7 @@ def print_help(parser: ArgumentParser):
 
     # additional help
     print()
-    print("Available commands: ")
+    rprint("[bold cyan]Available commands: ")
 
     command_help_map = [
         [name, func.__doc__.strip()]

linodecli/plugins/obj/__init__.py

@@ -8,7 +8,6 @@
 from datetime import datetime
 
 from rich.table import Table
-from rich.text import Text
 
 from linodecli.plugins.obj.config import DATE_FORMAT
 
@@ -126,7 +125,6 @@ def _borderless_table(data):
     """
     tab = Table.grid(padding=(0, 2, 0, 2))
     for row in data:
-        row = [Text.from_ansi(str(item)) for item in row]
         tab.add_row(*row)
 
     return tab