Tidy main command help. #4973
Tidy main command help. #4973
Conversation
|
|
cylc/flow/scripts/cylc.py
Outdated
| print( | ||
| 'Selected sub-commands ' | ||
| '(type "cylc help all" to see ALL sub-commands):' | ||
| ) |
There was a problem hiding this comment.
I feel the cylc help all bit was more prominent before when it was at the end of the list?
I.E. User scans down the list, can't find what they're looking for, ah cylc help all.
There was a problem hiding this comment.
Yep, you might be right there.
cylc/flow/scripts/cylc.py
Outdated
| Selected sub-commands are listed below. To view ALL sub-commands: | ||
| $ cylc help all | ||
|
|
There was a problem hiding this comment.
Selected sub-commands are listed below. To view ALL sub-commands:
Seems out of place. Not needed now the Usage: section is gone?
cylc/flow/scripts/cylc.py
Outdated
| Usage: | ||
| $ cylc help license # view the Cylc license (GPL-3.0) | ||
| $ cylc help all # list all commands | ||
| $ cylc validate <workflow> # validate a workflow configuration | ||
| $ cylc install <workflow> # install a workflow | ||
| $ cylc play <workflow> # run/resume a workflow | ||
| $ cylc scan # list all running workflows (by default) | ||
| $ cylc tui <workflow> # view/control workflows in the terminal | ||
| $ cylc stop <workflow> # stop a running workflow | ||
|
|
||
| Command Abbreviation: | ||
| # Commands can be abbreviated as long as there is no ambiguity in | ||
| # the abbreviated command: | ||
| $ cylc trigger WORKFLOW//CYCLE/TASK # trigger TASK in WORKFLOW | ||
| $ cylc trig WORKFLOW//CYCLE/TASK # ditto | ||
| $ cylc tr WORKFLOW//CYCLE/TASK # ditto | ||
| $ cylc t # Error: ambiguous command | ||
| $ cylc <sub-command> <OPTS> <ARGS> |
There was a problem hiding this comment.
I think cylc <sub-command> <OPTS> <ARGS> is a bit too abstract to be useful.
The previous section was good for showing the life-cycle of a workflow but was too long. Perhaps consider a "Quick Usage" or "Quick Start" section.
Quick Start:
$ cylc install <path> # install a workflow
$ cylc play <workflow_id> # run/resume a workflow
$ cylc stop <workflow_id> # stop a workflow
$ cylc clean <workflow_id> # delete an installed workflow
$ cylc help all # view all Cylc commands
With a shorter list of commands and a more descriptive name the opportunity for confusion should be less (especially if we put cylc help all at the end).
There was a problem hiding this comment.
The problem with the original, is without careful reading it could (evidently!) be taken as an exhaustive list of commands.
I quite like "Quick Start:" though as it suggests "just the most important commands for basic usage". I'll reformulate...
There was a problem hiding this comment.
Perhaps with that, we don' t need the "Selected Commands" list at the bottom, which most duplicated the list at top.
There was a problem hiding this comment.
Fair enough, the list is shorter now so the need to provide a short-list is less.
|
("man" command help?!) |
Co-authored-by: Oliver Sanders <oliver.sanders@metoffice.gov.uk>
Co-authored-by: Oliver Sanders <oliver.sanders@metoffice.gov.uk>
Co-authored-by: Oliver Sanders <oliver.sanders@metoffice.gov.uk>
|
Now looks like this: |
These changes close #4972
cylc help:Requirements check-list
CONTRIBUTING.mdand added my name as a Code Contributor.setup.cfgandconda-environment.yml.