Add CLI examples to docs for module messages and queries

[okwme]

Summary

Docs are a great place to understand how each module works but they don't provide examples of how a user would access the module. There's a section for basic CLI interactions but no examples of using, for example, vesting accounts from the CLI.

Problem Definition

A user needs to go through the --help command of the CLI to see documentation for each module's messages and queries. These should also be available somewhere within the docs.

Proposal

Add a section to each module called "CLI" or something similar that displays essentially the same content as the output from --help in order for users to see how the command is used. Maybe a set of examples with dummy responses as well? something like the swagger doc for CLI interactions would also be a suitable solution.

---

For Admin Use

• Not duplicate issue
• Appropriate labels applied
• Appropriate contributors tagged
• Contributor assigned/self-assigned

[alexanderbez]

I think we should just have a general client.md doc that explains both the gRPC (gateway) routes and the CLI commands. I think generally why we've avoided doing this, is because it's a burden to maintain and ensure it's kept up to date.

[okwme]

Do you think it would be easier to maintain if it lived closer to the module docs? Isn't that how current PRs ensure that the docs stay in sync with the code by looking just at the module doc? I would also think to look at the module when I had a question about the CLI for that module rather than a general client doc. I could also imagine it being useful to have the information in a single place as well as in each relevant module doc but that would make it even harder to ensure the content was up to date.

My preference would be module per module which would also break the work up well, right? Maybe something that @ryanchristo has thoughts about?

[alexanderbez]

Yeah we can have client.md in the spec/ directory of each module.

[ryanchristo]

I support this proposal. It would be nice to find a solution like swagger that autogenerates the documentation to help reduce the maintenance required. Either way, I think it would be a big improvement to the user experience. It might be nice to separate the gRPC routes and the CLI commands into separate files but starting with one client.md file also makes sense.

[ryanchristo]

cc @okwme @alexanderbez

I've created a draft pull request with an example of what a client.md page might look like for the authz module. Open to ideas on how this could be improved or how we might reduce the burden of maintenance. #10136

[alexanderbez]

Took a quick look, it looks greats @ryanchristo 👍

[ryanchristo]

A quick update on this issue. Two pull requests are ready to review adding the client.md document for authz and bank. I'm currently working on the client.md document for distribution. Here's a checklist for tracking:

• auth codefest issue docs: auth module add CLI examples to client.md in the spec/ directory #10287
• authz (@ryanchristo) docs: authz client spec #10136
• bank (@ryanchristo) docs: bank client spec #10147
• crisis codefest issue docs: crisis module add CLI examples to client.md in the spec/ directory #10288
• distribution (@ryanchristo) docs: distribution client spec #10159
• evidence codefest issue docs: evidence module add CLI examples to client.md in the spec/ directory #10289
• feegrant (@ryanchristo) docs: feegrant client spec #10160
• gov (@ryanchristo) docs: gov client spec #10196
• mint codefest issue docs: mint module add CLI examples to client.md in the spec/ directory #10290
• slashing codefest issue docs: slashing module add CLI examples to client.md in the spec/ directory #10291
• staking codefest issue docs: staking module add CLI examples to client.md in the spec/ directory #10292
• vesting codefest issue docs: vesting module add CLI examples to client.md in the spec/ directory #10293
• upgrade codefest issue docs: upgrade module add CLI examples to client.md in the spec/ directory #10294

[barriebyron]

@ryanchristo thanks so much for the awesome client.md docs you have already completed

I've created codefest issues for the remaining modules and added the issue link to you list
thanks @toschdev for the codefest idea, we love new contributors

check out October Codefest, invite your friends https://blog.cosmos.network/october-codefest-call-for-contributors-42ade37f4913

[amaury1093]

Seems like all modules have a client.md file now. Thanks!