Publish fancy guides/docs

[killercup]

I want to add some more examples and show them in a nice way, but I'm not yet sure how best to do that.

One idea:

• Add docs/ folder that is deploy via Github Pages (with Jekyll)
• put "literate Rust" in there (Markdown with code blocks)
• parse the Markdown files in there with waltz and test that code as subcrate(s) on CI

[vitiral]

Another idea: this library would be a great addition to use in the cookbook once it's API is nailed down. It could answer all sorts of "how do I do X for a CLI" with an ultra-simple example.

[vitiral]

we could also write examples in an examples/ module which literally only contains //! doc comments containing examples. This way the examples can be displayed offline easily through cargo doc (and the rust testrunner automatically tests them)

[killercup]

Yeah, I was thinking of cookbook style examples. I'd rather keep this separate from the Real Rust Cookbook, though, because a) this crate is fresh off the press and nowhere near stable and b) it's way easier to iterate here.

The reason I don't want to write these as doc comments for rustdoc to parse is simple: I need to test that the recipes work in external crates. I didn't even notice #9 until I tried using quicli as a real, external dependency.

Running the recipes as tests should not be a problem. waltz can extract arbitrary files from markdown source (you just have to annotate the file name), and we can trivially add a target like for d in */; { (echo "testing $d"; cd "$d"; ls | cargo test); }.

[vitiral]

Those all sound like good reasons to me! Waltz looks awesome also.

[polarathene]

The reason I don't want to write these as doc comments for rustdoc to parse is simple: I need to test that the recipes work in external crates.

mdbook had a recent release announcement, used for official Rust book and Rust by Example projects. In the reddit thread they mention a related crate for performing tests that can use external crates from crates.io performing tests better than rustdoc. May be of interest to you :)

Some gif animations showing a CLI project would be nice to see too(on this repo README and any docs as small examples of features? There is also an embeddable type of animation specifically for showing of CLI projects ASCIInema that might appeal :)

[killercup]

Thanks for the link, @polarathene! I don't think mdbook-test is helpful to me here, though (or maybe I misunderstood it). Have a look at #24 to see what kind of literate programming I want to use for the guides :)

[vitiral]

here is the initial release of ergo_fs. Check it out!

[vitiral]

@alexcrichton sorry that I accidentally sent you an invite to ergo! Know that you are totally welcome to join if you would like, but I didn't mean to spam you 😄

[killercup]

Oh no, don't invite Alex! I want him to work on tokio instead! :P

[killercup]

💥 https://killercup.github.io/quicli/ 💥