!48 docs(CLI): [#86] Probely SDK/CLI - Improve --help docs Closes #86

Author: João Silva

probely/cli/commands/findings/parsers.py

@@ -3,6 +3,11 @@
 from rich_argparse import RichHelpFormatter
 
 from probely.cli.commands.findings.get import findings_get_command_handler
+from probely.cli.commands.help_texts import (
+    SUB_COMMAND_AVAILABLE_ACTIONS_TITLE,
+    FINDINGS_F_SEARCH_TEXT,
+    FINDINGS_GET_COMMAND_DESCRIPTION_TEXT,
+)
 from probely.cli.common import show_help
 from probely.sdk.enums import FindingSeverityEnum, FindingStateEnum
 from probely.settings import FALSY_VALUES, TRUTHY_VALUES
@@ -49,7 +54,8 @@ def build_findings_filters_parser() -> argparse.ArgumentParser:
 
     findings_filters_parser.add_argument(
         "--f-search",
-        help="Filter findings by keyword",
+        metavar="SEARCH_TERM",
+        help=FINDINGS_F_SEARCH_TEXT,
         action="store",
     )
 
@@ -79,11 +85,13 @@ def build_findings_parser(commands_parser, configs_parser, output_parser):
         formatter_class=RichHelpFormatter,
     )
 
-    findings_command_parser = findings_parser.add_subparsers()
+    findings_command_parser = findings_parser.add_subparsers(
+        title=SUB_COMMAND_AVAILABLE_ACTIONS_TITLE,
+    )
 
     findings_get_parser = findings_command_parser.add_parser(
         "get",
-        help="Lists all findings",
+        help=FINDINGS_GET_COMMAND_DESCRIPTION_TEXT,
         parents=[configs_parser, findings_filter_parser, output_parser],
         formatter_class=RichHelpFormatter,
     )
@@ -92,7 +100,7 @@ def build_findings_parser(commands_parser, configs_parser, output_parser):
         "findings_ids",
         metavar="FINDING_ID",
         nargs="*",
-        help="IDs of findings to list",
+        help="Identifiers of the findings to list",
     )
 
     findings_get_parser.set_defaults(

probely/cli/commands/help_texts.py

@@ -0,0 +1,42 @@
+SUB_COMMAND_AVAILABLE_ACTIONS_TITLE = "Available Actions"
+
+TARGETS_GET_COMMAND_DESCRIPTION_TEXT = (
+    "List your account's targets. Use filters or identifiers to narrow the list"
+)
+TARGETS_ADD_COMMAND_DESCRIPTION_TEXT = "Add WEB or API targets you intend to scan"
+TARGETS_UPDATE_COMMAND_DESCRIPTION_TEXT = (
+    "Edit targets given by identifiers or the results of filters"
+)
+TARGETS_START_SCAN_COMMAND_DESCRIPTION_TEXT = (
+    "Scan targets given by identifiers or the results of filters"
+)
+TARGETS_DELETE_COMMAND_DESCRIPTION_TEXT = (
+    "Delete targets given by identifiers or the results of filters"
+)
+
+
+SCANS_GET_COMMAND_DESCRIPTION_TEXT = (
+    "List scans. Use filters or identifiers to narrow the list"
+)
+SCANS_PAUSE_COMMAND_DESCRIPTION_TEXT = (
+    "Pause running scans given by identifiers or the results of filters"
+)
+SCANS_CANCEL_COMMAND_DESCRIPTION_TEXT = (
+    "Stop unfinished scans given by identifiers or the results of filters"
+)
+SCANS_RESUME_COMMAND_DESCRIPTION_TEXT = (
+    "Resume paused scans given by identifiers or the results of filters"
+)
+
+
+FINDINGS_GET_COMMAND_DESCRIPTION_TEXT = (
+    "List findings. Use filters or identifiers to narrow the list"
+)
+
+TARGETS_F_SEARCH_TEXT = "Filter Targets matching name, url or labels"
+SCANS_F_SEARCH_TEXT = (
+    "Filter scans matching the scan URL, target name, target URL, or labels"
+)
+FINDINGS_F_SEARCH_TEXT = (
+    "Filter findings matching definition name, value, labels, or the target URL"
+)

probely/cli/commands/parsers.py

@@ -2,7 +2,6 @@
 
 from rich_argparse import RichHelpFormatter
 
-from probely.cli.commands.apply.apply import apply_command_handler
 from probely.cli.commands.findings.parsers import build_findings_parser
 from probely.cli.commands.scans.parsers import build_scans_parser
 from probely.cli.commands.targets.parsers import build_targets_parser
@@ -22,7 +21,7 @@ def build_file_parser():
         "--yaml-file",
         dest="yaml_file_path",
         default=None,
-        help="Path to yaml file. Accepts same payload as listed in API docs",
+        help="Path to file with content to apply. Accepts same payload as listed in API docs",
     )
 
     return file_parser
@@ -36,12 +35,12 @@ def build_configs_parser():
     )
     configs_parser.add_argument(
         "--api-key",
-        help="Set API KEY used for requests",
+        help="Authorization token to make requests to the API",
         default=None,
     )
     configs_parser.add_argument(
         "--debug",
-        help="Enable DEBUG mode setting",
+        help="Enables debug mode setting",
         action="store_true",
         default=False,
     )
@@ -59,7 +58,7 @@ def build_output_parser():
         "--output",
         type=str.upper,
         choices=OutputEnum.cli_input_choices(),
-        help="Presets for output formats",
+        help="Changes the output formats based on presets",
     )
     return output_parser
 
@@ -71,7 +70,7 @@ def build_cli_parser():
 
     probely_parser = argparse.ArgumentParser(
         prog="probely",
-        description="Welcome to Probely's CLI",
+        description="Probely's CLI. Check subcommands for available actions",
         formatter_class=RichHelpFormatter,
     )
     probely_parser.add_argument(
@@ -83,7 +82,9 @@ def build_cli_parser():
         parser=probely_parser,
     )
 
-    commands_parser = probely_parser.add_subparsers()
+    commands_parser = probely_parser.add_subparsers(
+        title="Subcommands for available contexts"
+    )
 
     build_targets_parser(commands_parser, configs_parser, file_parser, output_parser)
     build_scans_parser(commands_parser, configs_parser, file_parser, output_parser)

probely/cli/commands/scans/parsers.py

@@ -2,6 +2,14 @@
 
 from rich_argparse import RichHelpFormatter
 
+from probely.cli.commands.help_texts import (
+    SCANS_PAUSE_COMMAND_DESCRIPTION_TEXT,
+    SCANS_CANCEL_COMMAND_DESCRIPTION_TEXT,
+    SCANS_RESUME_COMMAND_DESCRIPTION_TEXT,
+    SCANS_GET_COMMAND_DESCRIPTION_TEXT,
+    SUB_COMMAND_AVAILABLE_ACTIONS_TITLE,
+    SCANS_F_SEARCH_TEXT,
+)
 from probely.cli.commands.scans.cancel import scans_cancel_command_handler
 from probely.cli.commands.scans.get import scans_get_command_handler
 from probely.cli.commands.scans.pause import scans_pause_command_handler
@@ -16,12 +24,13 @@ def build_scan_filters_parser() -> argparse.ArgumentParser:
         add_help=False,
         formatter_class=RichHelpFormatter,
     )
+
     scan_filters_parser.add_argument(
         "--f-search",
+        metavar="SEARCH_TERM",
         action="store",
         default=None,
-        metavar="SEARCH TERM",
-        help="Keyword to match with Scan URL, Target name, URL or labels",
+        help=SCANS_F_SEARCH_TEXT,
     )
 
     scan_filters_parser.add_argument(
@@ -51,7 +60,7 @@ def build_scan_filters_parser() -> argparse.ArgumentParser:
                 default=None,
                 metavar="DATETIME",
                 help=(
-                    f"Show scans {date_field} {description} the specified date or datetime."
+                    f"Filter scans {date_field} {description} the specified date or datetime."
                 ),
             )
     return scan_filters_parser
@@ -70,54 +79,77 @@ def build_scans_parser(commands_parser, configs_parser, file_parser, output_pars
         formatter_class=RichHelpFormatter,
     )
 
-    scans_command_parser = scans_parser.add_subparsers()
+    scans_command_parser = scans_parser.add_subparsers(
+        title=SUB_COMMAND_AVAILABLE_ACTIONS_TITLE,
+    )
 
     scan_filters_parser = build_scan_filters_parser()
 
-    scans_cancel_parser = scans_command_parser.add_parser(
-        "cancel",
+    scans_get_parser = scans_command_parser.add_parser(
+        "get",
+        help=SCANS_GET_COMMAND_DESCRIPTION_TEXT,
         parents=[configs_parser, scan_filters_parser, output_parser],
         formatter_class=RichHelpFormatter,
     )
-    scans_cancel_parser.add_argument(
+    scans_get_parser.add_argument(
         "scan_ids",
         metavar="SCAN_ID",
         nargs="*",
-        help="IDs of scans to cancel",
+        help="Identifiers of the scans to list",
         default=None,
     )
-    scans_cancel_parser.set_defaults(
-        command_handler=scans_cancel_command_handler,
-        parser=scans_cancel_parser,
+    scans_get_parser.set_defaults(
+        command_handler=scans_get_command_handler,
+        parser=scans_get_parser,
     )
 
-    scans_get_parser = scans_command_parser.add_parser(
-        "get",
+    scans_pause_parser = scans_command_parser.add_parser(
+        "pause",
+        help=SCANS_PAUSE_COMMAND_DESCRIPTION_TEXT,
         parents=[configs_parser, scan_filters_parser, output_parser],
         formatter_class=RichHelpFormatter,
     )
-    scans_get_parser.add_argument(
+    scans_pause_parser.add_argument(
         "scan_ids",
         metavar="SCAN_ID",
         nargs="*",
-        help="IDs of Scans to list",
+        help="Identifiers of the scans to pause.",
         default=None,
     )
-    scans_get_parser.set_defaults(
-        command_handler=scans_get_command_handler,
-        parser=scans_get_parser,
+    scans_pause_parser.set_defaults(
+        command_handler=scans_pause_command_handler,
+        parser=scans_pause_parser,
+    )
+
+    scans_cancel_parser = scans_command_parser.add_parser(
+        "cancel",
+        help=SCANS_CANCEL_COMMAND_DESCRIPTION_TEXT,
+        parents=[configs_parser, scan_filters_parser, output_parser],
+        formatter_class=RichHelpFormatter,
+    )
+    scans_cancel_parser.add_argument(
+        "scan_ids",
+        metavar="SCAN_ID",
+        nargs="*",
+        help="Identifiers of the scans to cancel",
+        default=None,
+    )
+    scans_cancel_parser.set_defaults(
+        command_handler=scans_cancel_command_handler,
+        parser=scans_cancel_parser,
     )
 
     scans_resume_parser = scans_command_parser.add_parser(
         "resume",
+        help=SCANS_RESUME_COMMAND_DESCRIPTION_TEXT,
         parents=[configs_parser, scan_filters_parser, output_parser],
         formatter_class=RichHelpFormatter,
     )
     scans_resume_parser.add_argument(
         "scan_ids",
         metavar="SCAN_ID",
         nargs="*",
-        help="IDs of scans to resume",
+        help="Identifiers of the scans to resume",
         default=None,
     )
     scans_resume_parser.add_argument(
@@ -129,19 +161,3 @@ def build_scans_parser(commands_parser, configs_parser, file_parser, output_pars
         command_handler=scans_resume_command_handler,
         parser=scans_resume_parser,
     )
-    scans_pause_parser = scans_command_parser.add_parser(
-        "pause",
-        parents=[configs_parser, scan_filters_parser, output_parser],
-        formatter_class=RichHelpFormatter,
-    )
-    scans_pause_parser.add_argument(
-        "scan_ids",
-        metavar="SCAN_ID",
-        nargs="*",
-        help="IDs of scans to pause",
-        default=None,
-    )
-    scans_pause_parser.set_defaults(
-        command_handler=scans_pause_command_handler,
-        parser=scans_pause_parser,
-    )