docs: add examples to readme

[joshka]

• Add a readme.rs example (rendered)
• Use VHS to generate the output gifs
• Adds a script to generate and publish all the gifs in one go
• Images are published to VHS rather than committed to the repo to avoid
  bloating the repo size

See https://github.com/charmbracelet/vhs for more info on VHS

Alternative to: #258

[joshka]

Ping @mitsuhiko @pksunkara any thoughts on merging this?

[pksunkara]

There's quite a bit of duplication in the readme and the example/readme.rs file. Is there a way to avoid this?

[joshka]

There's quite a bit of duplication in the readme and the example/readme.rs file. Is there a way to avoid this?

I'm unaware of any approach which would help remove this duplication (in a static readme doc) based on what this is doing.

The code in README.md is the same as the code which is run to produce the images that are used in the readme to document that code. Or put another way, readme.rs tests that the code in README.md is correct.

You could instead just link to the code, but I think it's reasonable to be able to see code and effect side by side like this. It helps a reader visualize the parameters and their effect.

While there are tools like cargo-rdme which can generate a readme from a lib.rs, and alternative ideas like using an include_str! macro to pull code from files into a doc comment, neither of these help with generating the many parts of a doc like this where you're including examples in a way which provide guidance on what each of the prompt types do like this.

You might consider using cargo-rdme to generate the readme, but the code will still be duplicated between readme.rs and lib.rs.

Oddly - TIL that a readme.rs gets rendered by github as text if you browse to the examples folder, so it could be worth renaming that to readme-examples.rs See https://github.com/console-rs/dialoguer/tree/a9428d4e6601949112fe2194b9ae64c70d8d6f99/examples