Add examples to commands' --help output

[tico24]

Summary

The Argo CLI has a lot of commands for which we provide no example in the --help output.

Motivation

Examples are awesome.

Proposal

For each item in this checklist, add an Example field. EDIT by agilgur5: See already-checked items for inspiration, use similar style & examples when possible, such as argo list for argo archive list, etc.

In some cases, the code itself may provide sufficient information to write some examples. For other commands, you may have to read through the docs to find or create examples.

--- list has been updated & modified by agilgur5 ---

argo commands

• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/cp.go#L30
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/delete.go#L27
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/get.go#L22
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/list.go#L64 -- Completed in docs: Add an example field to argo list command. Fixes #11898 #12076
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/lint.go#L26
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/logs.go#L27
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/node.go#L29
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/resubmit.go#L37
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/resume.go#L22
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/retry.go#L40
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/stop.go#L38
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/submit.go#L32
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/suspend.go#L14
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/terminate.go#L46
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/wait.go#L12
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/watch.go#L15

argo executor-plugin commands

• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/executorplugin/build.go#L13

argo archive commands

• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/archive/list.go#L25
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/archive/delete.go#L14
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/archive/resubmit.go#L39
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/archive/retry.go#L42
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/archive/list_label_keys.go#L14
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/archive/get.go#L21
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/archive/list_label_values.go#L18

argo auth commands

• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/auth/token.go#L13

argo template commands

• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/template/create.go#L25
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/template/list.go#L24
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/template/delete.go#L19
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/template/lint.go#L19
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/template/get.go#L20

argo cluster-template commands

• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/clustertemplate/create.go#L25 -- Completed in docs: Add an example field to argo cluster-template create command. Fixes #11898 #12101
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/clustertemplate/list.go#L22 -- Completed in docs: Add an example field to argo cluster-template list command. Fixes #11898 #12106
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/clustertemplate/delete.go#L18
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/clustertemplate/lint.go#L19
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/clustertemplate/get.go#L20

argo cron commands

• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/cron/create.go#L32
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/cron/list.go#L28
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/cron/resume.go#L15
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/cron/delete.go#L15
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/cron/suspend.go#L15
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/cron/lint.go#L19
• https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/cron/get.go#L23

Note: I generated the list with this command which I liberated from @crenshaw-dev...

find ./cmd -name '*.go' -print | xargs grep -n -r '&cobra.Command{' | sed "s/^./- [ ] https:\/\/github.com\/argoproj\/argo-workflows\/tree\/$(git rev-parse --short HEAD)/" | sed 's/\.go:/\.go#L/' | awk -F: '{print $1":"$2}' | pbcopy

EDIT: list was further updated & modified by agilgur5

---

Message from the maintainers:

Love this enhancement proposal? Give it a 👍. We prioritise the proposals with the most 👍.

[Jaishree2310]

@tico24 Can you please assign this issue to me ?

[tico24]

I think the idea is that users take each one and do a PR for each. It helps with people's Hacktober stats or something.

[alok1929]

Hey, I would like to integrate this into the help : https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/cron/lint.go#L19

Should I use docker to setup the dev environment or how do I do it ? Thanks in advance!!!

@tico24

[agilgur5]

@tico24 could you make some modifications to this list? it is a bit naive right now.

for example, argoexec is the Executor that is primarily used internally, so that's not very user-facing and I would suggest we remove that from this list (especially as Executor work is not necessarily a "good first issue").

similarly, most of the root.go ones are just top-level holders for subcommands (and already list out the subcommands in help text), so there's no real examples to be had for them (except for how to print the help text, which is redundant if you literally just printed it out). I think those should be removed as well

[shabeebk]

I was hoping to take some files to start with, but already a lot of them have the example. Is the list in the description updated? It looks like the reality is different.

Can we fix the list once?

cc @agilgur5 as you created this one. 😉

[agilgur5]

cc @agilgur5 as you created this one. 😉

I didn't create it, @tico24 did, that's why I can't edit it. Otherwise I would have done so already.

There are definitely still many commands without examples, though see my above linked comment about ones that should be excluded.

[shabeebk]

Thanks @agilgur5 for the response. Let me have a look at your comment on e again. 😊

[agilgur5]

I didn't create it, @tico24 did, that's why I can't edit it. Otherwise I would have done so already.

Ok I'm now an Approver (as of today), so I now have permissions to edit other people's comments. I've fairly significantly edited the list and it should be up-to-date and improved now, as well as categorized