[docs] Add output to all examples

[nyurik]

When viewing examples, it is very hard to figure out what they do without running them, which requires substantial efforts. I have added the output of all examples at the top.

Also, two tiny spelling mistakes - in the readme and in the rename_all.

In case anyone wants to auto-generate something similar, I used this helper script, and made a few minor line manipulations afterwards.

run() {
  RES=$(cargo run -q --example "$1" -- --help 2> /dev/null | sed -e 's#^#//! #' )
  { echo "//! Running this example with --help prints this message:" ; echo "//! -----------------------------------------------------" ; echo "$RES" ; echo "//! -----------------------------------------------------" ; echo "" ; cat "examples/$1.rs" ; } > "$1.rs"
  rm "examples/$1.rs"
  mv "$1.rs" "examples/"
}

run after_help
run at_least_two

[epage]

FYI clap v3 has output for all examples, for example

• The derive tutorial
• All the other cookbook-like examples

We use trycmd, a CLI snapshotting tool that sort-of understands markdown, to verify and update the examples.

[TeXitoi]

https://github.com/TeXitoi/structopt/blob/master/examples/README.md was supposed to "document" the examples. Don't it do its job?

[nyurik]

Thanks @epage, this approach would clearly be better! Could you point to the code that actually does the .md updating?

@TeXitoi the oneliners in the readme help find the right example, but it does not explain the details of each. Whenever I studied individual examples, I kept being confused about the specifics of each feature. Running the code with the --help instantly solved most of my confusion. It clearly showed how structopt params affected the result. At the same time downloading and running each example seems a bit excessive for most users, so why not help them? My only concern with the @epage suggestion is the separation of the code and documentation -- one must look into both the readme and the code at the same time to see how they correspond.

[TeXitoi]

OK. Tell me if you want to change something or if I merge as is.

[nyurik]

@TeXitoi I think we can merge it as is for the immediate benefit, and since it won't stop us from improving later. Going forward, we may want to adapt the clearly better path suggested by @epage -- to generate/update those docs automagically. It would be a bit more involved though, and may take longer to implement.

[TeXitoi]

Thanks for your contribution!

[epage]

@nyurik most of the heavy lifting comes from trycmd. Clap just defines the example test.

Unsure how much is worth continuing to iterate on this since clap v3 will replace structopt and we are weeks away from 3.0.0 from being released.