fix: improve help text (#436)

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

@@ -73,13 +73,22 @@ def validate_parameters(ctx, param, value):
 
 @cli_bundle.command(name="submit")
 @click.option(
-    "-p", "--parameter", multiple=True, callback=validate_parameters, help="Job template parameters"
+    "-p",
+    "--parameter",
+    multiple=True,
+    callback=validate_parameters,
+    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.")
+@click.option(
+    "--priority",
+    type=int,
+    default=50,
+    help="The priority of the job. Jobs with a higher priority run first.",
+)
 @click.option(
     "--max-failed-tasks-count",
     type=int,
@@ -92,9 +101,10 @@ def validate_parameters(ctx, param, value):
 )
 @click.option(
     "--job-attachments-file-system",
-    help="The method for accessing files from job attachments. "
-    + "COPIED means to copy files to the host and "
-    + "VIRTUAL means to load files when needed with a virtual 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. 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(
@@ -105,7 +115,7 @@ def validate_parameters(ctx, param, value):
 @click.option(
     "--require-paths-exist",
     is_flag=True,
-    help="Require all input paths to exist",
+    help="Return an error if any input files are missing.",
 )
 @click.option(
     "--submitter-name",
@@ -128,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)
@@ -256,7 +266,7 @@ def _decide_cancel_submission(upload_group: AssetUploadGroup) -> bool:
 @click.option(
     "--browse",
     is_flag=True,
-    help="Allows user to choose Bundle and adds a 'Load a different job bundle' option to the Job-Specific Settings UI",
+    help="Opens a folder browser to select a bundle.",
 )
 @click.option(
     "--install-gui",
@@ -283,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,71 +15,33 @@
 @_handle_error
 def cli_config():
     """
-    Manage AWS Deadline Cloud's workstation configuration.
-
-    The available AWS Deadline Cloud settings are:
-
-    defaults.aws_profile_name:
-
-        The default AWS profile to use for AWS Deadline Cloud commands. Set to '' to use the default credentials. Other settings are saved with the profile.
-
-    defaults.farm_id:
-
-        The default farm ID to use for job submissions or CLI operations.
-
-    defaults.queue_id:
-
-        The default queue ID to use for job submissions or CLI operations.
-
-    settings.storage_profile_id:
-
-        The storage profile that this workstation conforms to. It specifies
-        where shared file systems are mounted, and where named job attachments
-        should go.
-
-    defaults.job_id:
-
-        The Job ID to use by default. This gets updated by job submission so is normally the most recently submitted job.
-
-    settings.job_history_dir:
-
-        The directory in which to create new job bundles for submitting to AWS Deadline Cloud, to produce a history of job submissions.
-
-    settings.auto_accept:
-
-        Flag to automatically confirm any confirmation prompts.
-
-    settings.log_level:
-
-        Setting to change the log level. Must be one of ["ERROR", "WARNING", "INFO", "DEBUG"]
-
-    defaults.job_attachments_file_system:
-
-        Setting to determine if attachments are copied on to workers before a job executes
-        or fetched in realtime. Must be one of ["COPIED", "VIRTUAL"]
-
-    telemetry.opt_out:
-
-        Flag to specify opting out of telemetry data collection.
+    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()
 
 
@@ -107,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.
@@ -120,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(