argo-workflows icon indicating copy to clipboard operation
argo-workflows copied to clipboard

Published 20 hours ago • verified publisher icon argoproj

Add examples to commands' --help output

Open tico24 opened this issue 1 year ago • 7 comments

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. See already-checked items for inspiration.

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.

  • [ ] https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argoexec/commands/agent.go#L35
  • [ ] https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argoexec/commands/agent.go#L76
  • [ ] https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argoexec/commands/kill.go#L13
  • [x] https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argoexec/commands/artifact/delete.go#L26
  • [ ] https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argoexec/commands/artifact/root.go#L8
  • [ ] https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argoexec/commands/emissary.go#L39
  • [ ] https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/completion.go#L118
  • [ ] https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/list.go#L64
  • [x] 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/executorplugin/build.go#L13
  • [ ] https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/executorplugin/root.go#L8
  • [x] 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/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/root.go#L8
  • [ ] https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/archive/list_label_values.go#L18
  • [ ] 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/auth/token.go#L13
  • [ ] https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/auth/root.go#L8
  • [ ] 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/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
  • [ ] https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/template/root.go#L8
  • [ ] 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/wait.go#L12
  • [ ] 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/logs.go#L27
  • [ ] 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/suspend.go#L14
  • [x] 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/lint.go#L26
  • [ ] https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/clustertemplate/create.go#L25
  • [ ] https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/clustertemplate/list.go#L22
  • [ ] 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
  • [ ] https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/clustertemplate/root.go#L8
  • [ ] 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/node.go#L29
  • [ ] https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/root.go#L26
  • [ ] 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
  • [ ] https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/cron/root.go#L8
  • [ ] https://github.com/argoproj/argo-workflows/tree/1f66a399e/cmd/argo/commands/watch.go#L15

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

Message from the maintainers:

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

tico24 avatar Sep 28 '23 14:09 tico24

@tico24 Can you please assign this issue to me ?

Jaishree2310 avatar Sep 29 '23 13:09 Jaishree2310

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.

tico24 avatar Sep 29 '23 14:09 tico24

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

alok1929 avatar Oct 02 '23 04:10 alok1929

@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

agilgur5 avatar Oct 11 '23 23:10 agilgur5

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. 😉

shabeebk avatar Jan 23 '24 15:01 shabeebk

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.

agilgur5 avatar Jan 23 '24 16:01 agilgur5

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

shabeebk avatar Jan 23 '24 16:01 shabeebk

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

agilgur5 avatar Feb 05 '24 21:02 agilgur5