Organize etcdctl commands and add more documents

[ah8ad3]

What would you like to be added?

I want commands of etcdctl to be organized and documented in a better way.

1. For organizing i suggest to remove nested part of commands for example instead of having this:

        user add                Adds a new user
        user delete             Deletes a user
        user get                Gets detailed information of a user
        user grant-role         Grants a role to a user
        user list               Lists all users
        user passwd             Changes password of user
        user revoke-role        Revokes a role from a user

We can do something like this:

      Basic KV commands:
        del                  Removes the specified key or range of keys [key, range_end)
        get                  Gets the key or a range of keys
        put                  Puts the given key into the store

      Management Commands:
        user                  User related commands
        role                  Role related commands

And rest of this for other commands.

2. For documenting i suggest to make the documents and help texts for commands better and more helpful throw some examples and define better. For example when we invoke etcdctl leahe -h we get

NAME:
        lease - Lease related commands

USAGE:
        etcdctl lease <subcommand> [flags]

Maybe we can do something like this:

NAME:
        lease - Lease related commands

Description:
        Leases in etcd act as timers for data, automatically deleting keys when their associated lease expires.

USAGE:
        etcdctl lease <subcommand> [flags]

        etcdctl lease grant 60   # Creates a lease that lasts 60 seconds

        etcdctl lease keep-alive <lease_id> --once # Resets the keep-alive time to its original value and cobrautl.Exits immediately

Add a one line description so new users can understand what it is without going and searching for what is the lease, it's a tradeoff we don't want to throw the whole document here just a little sip of what is it. And put some popular usages in the USAGE section would be nice too.

Why is this needed?

As a newcomer to etcdctl it was hard for me to understand what it does at first, i was constantly searching the websites for commands to understand some of it. To enhance user experience, I propose implementing measures to clarify command functionalities upfront, easing the learning curve.

Also i think the first view of etcdctl -h is a little bit crowded and i believe with removing some subcommands that are not necessarry to show at first and style it a little bit this way users are greeted with a more intuitive interface.

[ah8ad3]

I want to get more involve in etcd community and i think with this issue i can help to make etcdctl better and also understand the basics and hopefully start working on core of etcd. If team approves, i would like to define some tasks and start working on this issue.

[ah8ad3]

/area documentation /area etcdctl

[ivanvc]

I can't think of any reason we wouldn't want to do this. I'd suggest opening PRs; the task sounds massive, though, so maybe we should follow a targeted approach to individual subcommands to open it up to discussion.

@jmhbnz, any thoughts on this?

[jmhbnz]

Hey @ah8ad3 - Thanks for raising this. I am absolutely on board with improving the built in documentation. I do actually like seeing all the available subcommands at once rather than gating them behind additional -h commands but that is just personal preference and if community consensus is to change it that is no problem.

If you can see gaps for documentation please feel free to start raising some pull requests, thanks!

/assign @ah8ad3

[ah8ad3]

Thanks @jmhbnz @ivanvc, I'll try to create a TODO list and start working on it.

[ah8ad3]

My perspective is these tasks:

• [ ] organize the commands of etcdctl just grouping similar commands together.

add description and some sample usages/result in these files

• [ ] alarm - alarm disarm
• [ ] auth
• [ ] check - check datascale - check perf
• [ ] compaction
• [ ] defrag
• [ ] downgrade
• [ ] elect
• [ ] endpoint
• [ ] lease
• [ ] lock
• [ ] make-mirror
• [ ] save
• [ ] txn
• [ ] user

Just in case as an example the document of etcdctl snapshot is

COMMANDS:
	save	Stores an etcd node backend snapshot to a given file

I expect etcdctl snapshot save would run but after running i get Error: snapshot save expects one argument. So the goal is to clarify that in the documents of etcdctl snapshot.