Specifying usage examples in the spec

[jose-fully-ported]

The dokku project uses some faux reflection and fancy footwork to generate cli help output as well as markdown docs from files. One thing that is nice is that we can show examples to users for usage.

I'm wondering if that would be possible to somehow spec out. Examples have a cli command as well as a description of the command, and are shown in the section for that particular subcommand.

[jdx]

Those are neat examples, and I think it's related to the problem I kind of need usage for—which might be helpful for you.

I want the ability to "mount" clis into mise-en-place, specifically for tasks so you can do mise run sql --help and see output for some defined "task"—which is itself a CLI—but also generate MD docs for the project README and shell completions. Seems like you have a similar problem.

What would be useful, of course, is if we had a library of common CLIs like psql. I've actually found at least a couple of good places I think we can use to seed the data—AI might actually help a lot here too.

• https://github.com/withfig/autocomplete/tree/master/src
• https://github.com/sigoden/argc-completions

But I'm not totally sure what you're asking here, are you asking for example usage specs that use some common CLIs so people reading the docs know what to expect? Or are you asking about examples of using a CLI to put into documentation like this:

USAGE mycli

DESCRIPITON
....

EXAMPLES
    $ mycli foo
    ...

[josegonzalez]

Back, this time with the correct github account.

---

What I'm looking for is some way in the usage spec to define examples for a given subcommand. Something like:

cmd "config" help="Manage the CLI config" {
  example invoke="mycli config" description="Show all the config values" output="key=value\nnew_key=new_value"
}

These examples would show up in the generated manpages as well as in the help output for a given command.

Here is an example of what the shell output might look like:

[jdx]

there is support for examples:

usage/src/parse/cmd.rs

Line 32 in 3f0f16c

pub examples: Vec<SpecExample>,

though I'm not sure if I have documented it or not

[josegonzalez]

Yeah if you could provide an example of usage/output, I can figure out if this would be suitable for my usage or propose spec changes.