docs: improve doc strings text #436
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
ddneilson
requested changes
Aug 28, 2024
epmog
requested changes
Aug 28, 2024
Comment on lines
17
to
18
| Manage AWS Deadline Cloud's workstation configuration. Config options are organized | ||
| and documented in config_file.SETTINGS. |
There was a problem hiding this comment.
What steps does a user take to then figure this information from the help text? Do they have to go code spelunking? I wonder if we can avoid that. Example:
(deadline) bash-3.2$ deadline config
Usage: deadline config [OPTIONS] COMMAND [ARGS]...
Manage AWS Deadline Cloud's workstation configuration. Config options are
organized and documented in config_file.SETTINGS.
Options:
-h, --help Show this message and exit.
Commands:
get Gets an AWS Deadline Cloud workstation configuration setting.
gui Open the workstation configuration settings GUI.
set Sets an AWS Deadline Cloud workstation configuration setting.
show Show AWS Deadline Cloud's current workstation configuration.
If we do change this, the get and set command will also have to change:
(deadline) bash-3.2$ deadline config set --help
Usage: deadline config set [OPTIONS] SETTING_NAME VALUE
Sets an AWS Deadline Cloud workstation configuration setting.
For example `deadline config set defaults.farm_id <farm-id>`. Run `deadline
config --help` to show available settings.
Options:
-h, --help Show this message and exit.
There was a problem hiding this comment.
Wrapping the documentation into deadline config show.
There was a problem hiding this comment.
Excerpt of sample output:
> deadline config show
AWS Deadline Cloud configuration file:
/Users/crowest/.deadline/config
deadline-cloud-monitor.path: ...
The filesystem path to Deadline Cloud monitor, set during login process.
defaults.aws_profile_name: ...
The AWS profile name to use by default. Set to '' to use the default
credentials. Other settings are saved with the profile.
settings.job_history_dir: ~/.deadline/job_history/ ... (default)
The directory in which to place the job submission history for this AWS
profile name.
defaults.farm_id: farm-281174...
The Farm ID to use by default.
settings.storage_profile_id: (default)
The storage profile that this workstation conforms to. It specifies where
shared file systems are mounted, and where named job attachments should go.
defaults.queue_id: queue-38906...
The Queue ID to use by default.
| "[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="The resolution method to use when a file already exists:\n" |
There was a problem hiding this comment.
starting with resolution feels odd to me, but I guess that's what the option is named. "How to handle existing files" might be a shorter way to put it. I think it's probably fine though. Just musing out loud.
|
Change looks good, just a few suggestions. 2 additional things that don't get captured in the diff:
for example: deadline isn't truncated but there's also a lot of self-referential but same with other ones like Might make sense to include that here in this change? |
Signed-off-by: Stephen Crowe <[email protected]>
Signed-off-by: Stephen Crowe <[email protected]>
|
|
Sample output from |
ddneilson
approved these changes
Aug 30, 2024
Merged
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What was the problem/requirement? (What/Why)
The client includes help text for its commands, and some of the help text could be improved.
What was the solution? (How)
Update help text as needed.
Fixes #324
Fixes #365
What is the impact of this change?
Someone can more easily understand how to use the client.
How was this change tested?
Have you run
hatch run test?Yes
Have you run
hatch run integ:test? SeeDEVELOPMENT.mdon "Run integration tests"No
Was this change documented?
Yes
Is this a breaking change?
No
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.