From 343bf7b18e1d32cb50445f0a9f28d8ad4825dbae Mon Sep 17 00:00:00 2001 From: Stephen Crowe Date: Fri, 30 Aug 2024 07:50:35 -0700 Subject: [PATCH] fix: improve help text (#436) Signed-off-by: Stephen Crowe --- src/deadline/client/api/_submit_job_bundle.py | 2 +- src/deadline/client/cli/_groups/auth_group.py | 6 +- .../client/cli/_groups/bundle_group.py | 32 ++++++--- .../client/cli/_groups/config_group.py | 69 +++++-------------- src/deadline/client/cli/_groups/farm_group.py | 8 +-- .../client/cli/_groups/fleet_group.py | 12 ++-- src/deadline/client/cli/_groups/job_group.py | 60 ++++++++-------- .../client/cli/_groups/queue_group.py | 16 ++--- .../client/cli/_groups/worker_group.py | 20 +++--- src/deadline/client/config/config_file.py | 2 +- .../deadline_client/cli/test_cli_config.py | 4 +- 11 files changed, 101 insertions(+), 130 deletions(-) diff --git a/src/deadline/client/api/_submit_job_bundle.py b/src/deadline/client/api/_submit_job_bundle.py index 4fa3e094..8ab007cf 100644 --- a/src/deadline/client/api/_submit_job_bundle.py +++ b/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: diff --git a/src/deadline/client/cli/_groups/auth_group.py b/src/deadline/client/cli/_groups/auth_group.py index 99a8c224..c9bd38c7 100644 --- a/src/deadline/client/cli/_groups/auth_group.py +++ b/src/deadline/client/cli/_groups/auth_group.py @@ -34,7 +34,7 @@ def _cli_on_pending_authorization(**kwargs): @_handle_error def cli_auth(): """ - Commands to handle AWS Deadline Cloud authentication. + Commands to handle authentication. """ @@ -42,9 +42,9 @@ def cli_auth(): @_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( diff --git a/src/deadline/client/cli/_groups/bundle_group.py b/src/deadline/client/cli/_groups/bundle_group.py index a920dc5c..e0190384 100644 --- a/src/deadline/client/cli/_groups/bundle_group.py +++ b/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 diff --git a/src/deadline/client/cli/_groups/config_group.py b/src/deadline/client/cli/_groups/config_group.py index 18c6d882..cea0b261 100644 --- a/src/deadline/client/cli/_groups/config_group.py +++ b/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,52 +15,7 @@ @_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. """ @@ -67,7 +23,7 @@ def cli_config(): @_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() @@ -75,10 +31,17 @@ def config_show(): 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 `. 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. diff --git a/src/deadline/client/cli/_groups/farm_group.py b/src/deadline/client/cli/_groups/farm_group.py index 29211bf3..993734ba 100644 --- a/src/deadline/client/cli/_groups/farm_group.py +++ b/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. """ diff --git a/src/deadline/client/cli/_groups/fleet_group.py b/src/deadline/client/cli/_groups/fleet_group.py index 5461778c..ec86f672 100644 --- a/src/deadline/client/cli/_groups/fleet_group.py +++ b/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( diff --git a/src/deadline/client/cli/_groups/job_group.py b/src/deadline/client/cli/_groups/job_group.py index 98ec16d6..c1d2b34e 100644 --- a/src/deadline/client/cli/_groups/job_group.py +++ b/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("--page-size", default=5, help="The number of items shown in the page.") -@click.option("--item-offset", default=0, help="The starting offset of the items.") +@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 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,11 +608,10 @@ def _assert_valid_path(path: str) -> None: ], case_sensitive=False, ), - help="The resolution method to use when a file already exists." - "Please choose one from the following options. If it is not provided, it defaults to CREATE_COPY:\n" - "[1] SKIP: Do not download these files\n" - "[2] OVERWRITE: Download these files and overwrite existing files\n" - "[3] CREATE_COPY: Download the file with a new name, appending '(1)' to the end", + 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", ) @click.option( "--yes", @@ -633,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'") @@ -660,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", @@ -676,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 .json", use diff --git a/src/deadline/client/cli/_groups/queue_group.py b/src/deadline/client/cli/_groups/queue_group.py index 7ac20bef..c28a124b 100644 --- a/src/deadline/client/cli/_groups/queue_group.py +++ b/src/deadline/client/cli/_groups/queue_group.py @@ -17,17 +17,17 @@ @_handle_error def cli_queue(): """ - Commands for AWS Deadline Cloud Queues. + Commands for queues. """ @cli_queue.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 queue_list(**args): """ - Lists the available Queues in AWS Deadline Cloud. + Lists the available queues. """ # Get a temporary config object with the standard options handled config = _apply_cli_options_to_config(required_options={"farm_id"}, **args) @@ -50,8 +50,8 @@ def queue_list(**args): @cli_queue.command(name="paramdefs") @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.") @_handle_error def queue_paramdefs(**args): """ @@ -75,12 +75,12 @@ def queue_paramdefs(**args): @cli_queue.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("--farm-id", help="The farm to use.") +@click.option("--queue-id", help="The queue to use.") @_handle_error def queue_get(**args): """ - Get the details of an AWS Deadline Cloud Queue. + Get the details of a queue. If Queue ID is not provided, returns the configured default Queue. """ diff --git a/src/deadline/client/cli/_groups/worker_group.py b/src/deadline/client/cli/_groups/worker_group.py index 6c2098d0..f179c2a9 100644 --- a/src/deadline/client/cli/_groups/worker_group.py +++ b/src/deadline/client/cli/_groups/worker_group.py @@ -17,20 +17,20 @@ @_handle_error def cli_worker(): """ - Commands to work with AWS Deadline Cloud Workers. + Commands to work with workers. """ @cli_worker.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("--fleet-id", help="The AWS Deadline Cloud Fleet to use.", required=True) -@click.option("--page-size", default=5, help="The number of items shown in the page.") -@click.option("--item-offset", default=0, help="The starting offset of the items.") +@click.option("--farm-id", help="The farm to use.") +@click.option("--fleet-id", help="The fleet to use.", required=True) +@click.option("--page-size", default=5, help="The number of workers to load at a time.") +@click.option("--item-offset", default=0, help="The index of the worker to start listing from.") @_handle_error def worker_list(page_size, item_offset, fleet_id, **args): """ - Lists the Workers in an AWS Deadline Cloud Fleet. + Lists the Workers in a fleet. """ # Get a temporary config object with the standard options handled config = _apply_cli_options_to_config(required_options={"farm_id"}, **args) @@ -62,13 +62,13 @@ def worker_list(page_size, item_offset, fleet_id, **args): @cli_worker.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.", required=True) -@click.option("--worker-id", help="The AWS Deadline Cloud Worker to get.", required=True) +@click.option("--farm-id", help="The farm to use.") +@click.option("--fleet-id", help="The fleet to use.", required=True) +@click.option("--worker-id", help="The worker to get.", required=True) @_handle_error def worker_get(fleet_id, worker_id, **args): """ - Get the details of an AWS Deadline Cloud worker. + Get the details of a worker. """ # Get a temporary config object with the standard options handled config = _apply_cli_options_to_config(required_options={"farm_id"}, **args) diff --git a/src/deadline/client/config/config_file.py b/src/deadline/client/config/config_file.py index 67007803..d84edadf 100644 --- a/src/deadline/client/config/config_file.py +++ b/src/deadline/client/config/config_file.py @@ -100,7 +100,7 @@ }, "settings.conflict_resolution": { "default": FileConflictResolution.NOT_SELECTED.name, - "description": "How to handle duplicate files when downloading (if a file with the same path/name already exists.)", + "description": "How to handle downloads if a file already exists", }, "settings.log_level": { "default": "WARNING", diff --git a/test/unit/deadline_client/cli/test_cli_config.py b/test/unit/deadline_client/cli/test_cli_config.py index c332cbc3..6b0eb2dc 100644 --- a/test/unit/deadline_client/cli/test_cli_config.py +++ b/test/unit/deadline_client/cli/test_cli_config.py @@ -120,8 +120,8 @@ def test_cli_config_show_modified_config(fresh_deadline_config): assert "farm-82934h23k4j23kjh" in result.output assert "queue-389348u234jhk34" in result.output assert "job-239u40234jkl234nkl23" in result.output - assert "settings.conflict_resolution:\n CREATE_COPY" in result.output - assert "settings.log_level:\n DEBUG" in result.output + assert "CREATE_COPY" in result.output + assert "DEBUG" in result.output assert "user-id-123abc-456def" in result.output # It shouldn't say anywhere that there is a default setting assert "(default)" not in result.output