Avoid truncated help text, improve config help

Signed-off-by: Stephen Crowe <[email protected]>

src/deadline/client/api/_submit_job_bundle.py

@@ -68,7 +68,7 @@ def create_job_from_job_bundle(
     submitter_name: str = "CLI",
 ) -> Union[str, None]:
     """
-    Creates a job in the AWS Deadline Cloud farm/queue configured as default for the
+    Creates a job in the farm/queue configured as default for the
     workstation from the job bundle in the provided directory.
 
     A job bundle has the following directory structure:

src/deadline/client/cli/_groups/auth_group.py

@@ -34,17 +34,17 @@ def _cli_on_pending_authorization(**kwargs):
 @_handle_error
 def cli_auth():
     """
-    Commands to handle AWS Deadline Cloud authentication.
+    Commands to handle authentication.
     """
 
 
 @cli_auth.command(name="login")
 @_handle_error
 def auth_login():
     """
-    Logs in to the AWS Deadline Cloud configured AWS profile.
+    Logs in to the Deadline-configured AWS profile.
 
-    This is for any profile type that AWS Deadline Cloud knows how to login to
+    This is for any profile type that Deadline knows how to login to
     Currently only supports Deadline Cloud monitor
     """
     click.echo(

src/deadline/client/cli/_groups/bundle_group.py

@@ -80,14 +80,14 @@ def validate_parameters(ctx, param, value):
     help='The values for the job template\'s parameters. Can be provided as key-value pairs, inline JSON strings, or as paths to a JSON or YAML document. If provided more than once, the values are combined in the order that they appear. Examples: --parameter MyParam=5 -p file://parameter_file.json -p \'{"MyParam": "5"}\'',
 )
 @click.option("--profile", help="The AWS profile to use.")
-@click.option("--farm-id", help="The AWS Deadline Cloud Farm to use.")
-@click.option("--queue-id", help="The AWS Deadline Cloud Queue to use.")
+@click.option("--farm-id", help="The farm to use.")
+@click.option("--queue-id", help="The queue to use.")
 @click.option("--name", help="The job name to use in place of the one in the job bundle.")
 @click.option(
     "--priority",
     type=int,
     default=50,
-    help="The priority of the job. The highest priority is 100.",
+    help="The priority of the job. Jobs with a higher priority run first.",
 )
 @click.option(
     "--max-failed-tasks-count",
@@ -102,8 +102,9 @@ def validate_parameters(ctx, param, value):
 @click.option(
     "--job-attachments-file-system",
     help="The method workers use to access job attachments. "
-    + "COPIED means to copy files to the worker and "
-    + "VIRTUAL means to load files as needed from a virtual file system.",
+    "COPIED means to copy files to the worker and VIRTUAL means to load "
+    "files as needed from a virtual file system. If VIRTUAL is selected "
+    "but not supported by a worker, it will fallback to COPIED.",
     type=click.Choice([e.value for e in JobAttachmentsFileSystem]),
 )
 @click.option(
@@ -137,7 +138,7 @@ def bundle_submit(
     **args,
 ):
     """
-    Submits an Open Job Description job bundle to AWS Deadline Cloud.
+    Submits an Open Job Description job bundle.
     """
     # Get a temporary config object with the standard options handled
     config = _apply_cli_options_to_config(required_options={"farm_id", "queue_id"}, **args)
@@ -265,7 +266,7 @@ def _decide_cancel_submission(upload_group: AssetUploadGroup) -> bool:
 @click.option(
     "--browse",
     is_flag=True,
-    help="Opens a file browser to select a bundle.",
+    help="Opens a folder browser to select a bundle.",
 )
 @click.option(
     "--install-gui",
@@ -292,7 +293,7 @@ def _decide_cancel_submission(upload_group: AssetUploadGroup) -> bool:
 @_handle_error
 def bundle_gui_submit(job_bundle_dir, browse, output, install_gui, submitter_name, **args):
     """
-    Opens GUI to submit an Open Job Description job bundle to AWS Deadline Cloud.
+    Opens a GUI to submit an Open Job Description job bundle.
     """
     from ...ui import gui_context_for_cli
 

src/deadline/client/cli/_groups/config_group.py

@@ -5,6 +5,7 @@
 """
 
 import click
+import textwrap
 
 from ...config import config_file
 from .._common import _handle_error
@@ -14,27 +15,33 @@
 @_handle_error
 def cli_config():
     """
-    Manage AWS Deadline Cloud's workstation configuration. Config options are organized
-    and documented in config_file.SETTINGS.
+    Manage Deadline's workstation configuration.
     """
 
 
 @cli_config.command(name="show")
 @_handle_error
 def config_show():
     """
-    Show AWS Deadline Cloud's current workstation configuration.
+    Show all workstation configuration settings and current values.
     """
     click.echo(f"AWS Deadline Cloud configuration file:\n   {config_file.get_config_file_path()}")
     click.echo()
 
     for setting_name in config_file.SETTINGS.keys():
         setting_value = config_file.get_setting(setting_name)
         setting_default = config_file.get_setting_default(setting_name)
-        if setting_value == setting_default:
-            click.echo(f"{setting_name}: (default)\n   {setting_value}")
-        else:
-            click.echo(f"{setting_name}:\n   {setting_value}")
+
+        # Wrap and indent the descriptions to 80 characters because they may be multiline.
+        setting_description: str = config_file.SETTINGS[setting_name].get("description", "")
+        setting_description = "\n".join(
+            f"   {line}" for line in textwrap.wrap(setting_description, width=77)
+        )
+
+        click.echo(
+            f"{setting_name}: {setting_value} {'(default)' if setting_value == setting_default else ''}"
+        )
+        click.echo(setting_description)
         click.echo()
 
 
@@ -63,7 +70,7 @@ def config_gui(install_gui: bool):
 @_handle_error
 def config_set(setting_name, value):
     """
-    Sets an AWS Deadline Cloud workstation configuration setting.
+    Sets a workstation configuration setting.
 
     For example `deadline config set defaults.farm_id <farm-id>`.
     Run `deadline config --help` to show available settings.
@@ -76,7 +83,7 @@ def config_set(setting_name, value):
 @_handle_error
 def config_get(setting_name):
     """
-    Gets an AWS Deadline Cloud workstation configuration setting.
+    Gets a workstation configuration setting.
 
     For example `deadline config get defaults.farm_id`.
     Run `deadline config --help` to show available settings.

src/deadline/client/cli/_groups/farm_group.py

@@ -17,7 +17,7 @@
 @_handle_error
 def cli_farm():
     """
-    Commands to work with AWS Deadline Cloud Farm resources.
+    Commands to work with farms.
     """
 
 
@@ -26,7 +26,7 @@ def cli_farm():
 @_handle_error
 def farm_list(**args):
     """
-    Lists the available Farms in AWS Deadline Cloud.
+    Lists the available farms.
     """
     # Get a temporary config object with the standard options handled
     config = _apply_cli_options_to_config(**args)
@@ -46,11 +46,11 @@ def farm_list(**args):
 
 @cli_farm.command(name="get")
 @click.option("--profile", help="The AWS profile to use.")
-@click.option("--farm-id", help="The AWS Deadline Cloud Farm to use.")
+@click.option("--farm-id", help="The farm to use.")
 @_handle_error
 def farm_get(**args):
     """
-    Get the details of an AWS Deadline Cloud farm.
+    Get the details of a farm.
 
     If farm ID is not provided, returns the configured default farm.
     """

src/deadline/client/cli/_groups/fleet_group.py

@@ -17,17 +17,17 @@
 @_handle_error
 def cli_fleet():
     """
-    Commands to work with AWS Deadline Cloud Fleet resources.
+    Commands to work with fleets.
     """
 
 
 @cli_fleet.command(name="list")
 @click.option("--profile", help="The AWS profile to use.")
-@click.option("--farm-id", help="The AWS Deadline Cloud Farm to use.")
+@click.option("--farm-id", help="The farm to use.")
 @_handle_error
 def fleet_list(**args):
     """
-    Lists the available Fleets in AWS Deadline Cloud.
+    Lists the available fleets.
     """
     # Get a temporary config object with the standard options handled
     config = _apply_cli_options_to_config(required_options={"farm_id"}, **args)
@@ -50,13 +50,13 @@ def fleet_list(**args):
 
 @cli_fleet.command(name="get")
 @click.option("--profile", help="The AWS profile to use.")
-@click.option("--farm-id", help="The AWS Deadline Cloud Farm to use.")
-@click.option("--fleet-id", help="The AWS Deadline Cloud Fleet to use.")
+@click.option("--farm-id", help="The farm to use.")
+@click.option("--fleet-id", help="The fleet to use.")
 @click.option("--queue-id", help="If provided, gets all Fleets associated with the Queue.")
 @_handle_error
 def fleet_get(fleet_id, queue_id, **args):
     """
-    Get the details of an AWS Deadline Cloud Fleet.
+    Get the details of a fleet.
     """
     if fleet_id and queue_id:
         raise DeadlineOperationError(

src/deadline/client/cli/_groups/job_group.py

@@ -54,20 +54,20 @@
 @_handle_error
 def cli_job():
     """
-    Commands to work with AWS Deadline Cloud Jobs.
+    Commands to work with jobs.
     """
 
 
 @cli_job.command(name="list")
 @click.option("--profile", help="The AWS profile to use.")
-@click.option("--farm-id", help="The AWS Deadline Cloud Farm to use.")
-@click.option("--queue-id", help="The AWS Deadline Cloud Queue to use.")
+@click.option("--farm-id", help="The farm to use.")
+@click.option("--queue-id", help="The queue to use.")
 @click.option("--page-size", default=5, help="The number of jobs to load at a time.")
 @click.option("--item-offset", default=0, help="The index of the job to start listing from.")
 @_handle_error
 def job_list(page_size, item_offset, **args):
     """
-    Lists the Jobs in an AWS Deadline Cloud Queue.
+    Lists the Jobs in a queue.
     """
     # Get a temporary config object with the standard options handled
     config = _apply_cli_options_to_config(required_options={"farm_id", "queue_id"}, **args)
@@ -118,13 +118,13 @@ def job_list(page_size, item_offset, **args):
 
 @cli_job.command(name="get")
 @click.option("--profile", help="The AWS profile to use.")
-@click.option("--farm-id", help="The AWS Deadline Cloud Farm to use.")
-@click.option("--queue-id", help="The AWS Deadline Cloud Queue to use.")
-@click.option("--job-id", help="The AWS Deadline Cloud Job to get.")
+@click.option("--farm-id", help="The farm to use.")
+@click.option("--queue-id", help="The queue to use.")
+@click.option("--job-id", help="The job to get.")
 @_handle_error
 def job_get(**args):
     """
-    Get the details of an AWS Deadline Cloud Job.
+    Get the details of a job.
     """
     # Get a temporary config object with the standard options handled
     config = _apply_cli_options_to_config(
@@ -144,14 +144,14 @@ def job_get(**args):
 
 @cli_job.command(name="cancel")
 @click.option("--profile", help="The AWS profile to use.")
-@click.option("--farm-id", help="The AWS Deadline Cloud Farm to use.")
-@click.option("--queue-id", help="The AWS Deadline Cloud Queue to use.")
-@click.option("--job-id", help="The AWS Deadline Cloud Job to cancel.")
+@click.option("--farm-id", help="The farm to use.")
+@click.option("--queue-id", help="The queue to use.")
+@click.option("--job-id", help="The job to cancel.")
 @click.option(
     "--mark-as",
     type=click.Choice(["CANCELED", "FAILED", "SUCCEEDED"], case_sensitive=False),
     default="CANCELED",
-    help="The task run status to mark the job as.",
+    help="The status to apply to all active tasks in the job.",
 )
 @click.option(
     "--yes",
@@ -161,7 +161,7 @@ def job_get(**args):
 @_handle_error
 def job_cancel(mark_as: str, yes: bool, **args):
     """
-    Cancel an AWS Deadline Cloud Job from running.
+    Cancel job from running.
     """
     # Get a temporary config object with the standard options handled
     config = _apply_cli_options_to_config(
@@ -593,11 +593,11 @@ def _assert_valid_path(path: str) -> None:
 
 @cli_job.command(name="download-output")
 @click.option("--profile", help="The AWS profile to use.")
-@click.option("--farm-id", help="The AWS Deadline Cloud Farm to use.")
-@click.option("--queue-id", help="The AWS Deadline Cloud Queue to use.")
-@click.option("--job-id", help="The AWS Deadline Cloud Job to use.")
-@click.option("--step-id", help="The AWS Deadline Cloud Step to use.")
-@click.option("--task-id", help="The AWS Deadline Cloud Task to use.")
+@click.option("--farm-id", help="The farm to use.")
+@click.option("--queue-id", help="The queue to use.")
+@click.option("--job-id", help="The job to use.")
+@click.option("--step-id", help="The step to use.")
+@click.option("--task-id", help="The task to use.")
 @click.option(
     "--conflict-resolution",
     type=click.Choice(
@@ -608,7 +608,7 @@ def _assert_valid_path(path: str) -> None:
         ],
         case_sensitive=False,
     ),
-    help="The resolution method to use when a file already exists:\n"
+    help="How to handle downloads if a file already exists:\n"
     "CREATE_COPY (default): Download the file with a new name, appending '(1)' to the end\n"
     "SKIP: Do not download the file\n"
     "OVERWRITE: Download and replace the existing file",
@@ -632,7 +632,7 @@ def _assert_valid_path(path: str) -> None:
 @_handle_error
 def job_download_output(step_id, task_id, output, **args):
     """
-    Download the output attached to an AWS Deadline Cloud Job.
+    Download a job's output.
     """
     if task_id and not step_id:
         raise click.UsageError("Missing option '--step-id' required with '--task-id'")
@@ -659,9 +659,9 @@ def job_download_output(step_id, task_id, output, **args):
 
 @cli_job.command(name="trace-schedule")
 @click.option("--profile", help="The AWS profile to use.")
-@click.option("--farm-id", help="The AWS Deadline Cloud Farm to use.")
-@click.option("--queue-id", help="The AWS Deadline Cloud Queue to use.")
-@click.option("--job-id", help="The AWS Deadline Cloud Job to trace.")
+@click.option("--farm-id", help="The farm to use.")
+@click.option("--queue-id", help="The queue to use.")
+@click.option("--job-id", help="The job to trace.")
 @click.option("-v", "--verbose", is_flag=True, help="Output verbose trace details.")
 @click.option(
     "--trace-format",
@@ -675,8 +675,7 @@ def job_download_output(step_id, task_id, output, **args):
 @_handle_error
 def job_trace_schedule(verbose, trace_format, trace_file, **args):
     """
-    EXPERIMENTAL - Print statistics about how a job, and optionally
-    write a trace file.
+    EXPERIMENTAL - Generate statistics from a completed job.
 
     To visualize the trace output file when providing the options
     "--trace-format chrome --trace-file <output>.json", use