Replace official "cheatsheet" with http://rustbyexample.com/

[brson]

http://rustbyexample.com/ is significantly better than our cheatsheet. Let's just endorse it by linking directly to it. That should encourage more contributions to rustbyexample to get it finished.

[brson]

Hm, there are some downsides to this: we can't verify the examples are correct, and they are no longer tied to a specific version. This should probably be in the 'extern resources' section if we add it to make it clear it's not official docs.

[thehydroimpulse]

I'm currently extending rustdoc for a refactored guide system and I'm implementing an extensible validator that rustbyexample could perhaps use rustdoc validate src/**/*.rs. However, this doesn't solve the issue of versions and being tied to the compiler's test suite.

[steveklabnik]

I'm currently extending rustdoc for a refactored guide system

ooh neat. Talking about this anywhere? I'd be interested in seeing it.

[japaric]

@brson

we can't verify the examples are correct

I'm using cronie.daily + travis to check that the examples stay up to date with rust nigthly, and I receive an e-mail whenever an example breaks. (I have yet to fix the examples that got broken today because of the ~str removal).

Each example is compiled, executed and the output is updated along with the site, whenever I rebuild it. (So the site should be WYSIWYG)

and they are no longer tied to a specific version

RBE follows nigthly, rather than sticking to an snapshot version. But I don't think that's a problem, because that's what rust-lang.org recommends. After we hit 1.0, I plan to add "What's new in 1.x" sections containing examples of new features/libraries, while keeping the 1.0 content unchanged.

@thehydroimpulse

I'm currently using rustc --no-trans --test $(each *.rs) (plus some -A flags to reduce the noise) to check that the examples stay compilable. How would rustdoc validate compare to that? "validate" sounds like it would check some output remains constant, (I'm thinking of python doctests) (Note: I haven't touched rustdoc yet)

[thehydroimpulse]

ooh neat. Talking about this anywhere? I'd be interested in seeing it.

@steveklabnik Here's the previous PR that I had opened: #14245 — that was with a Ruby static site generator. Now I have integrated some extra stuff into rustdoc to allow some more extensible docs (currated). This drops any previously required depenedencies such as Ruby and Bundler.

Somethings on the list:

• Extensible validator
• Layouts (Instead of hardcoding them into Rust files)
• Frontmatter (Yaml-like metadata within markdown files to specify arbitrary settings: title, layout, categories, etc...)

This will allow a refactor on the current tutorial and guide sections allowing a much nicer experience. All the work is currently being done within my fork (I'll be squashing my commits pretty soon) and I'll be re-opening that PR once I'm done.

@japaric The validator I'm working on allows multiple different types of inputs all wrapped in the same CLI interface. For example, you could do rustdoc validate docs/**/*.md and it would extract the rust code from the markdown and test each one, outputting the results in a neat manner. It would also allow things like specifying that a specific code block should not be validated and so forth.

[huonw]

Isn't that validate command already there as --test?

[thehydroimpulse]

@huonw It's an extension of that, yes.

[steveklabnik]

We now link to Rust By Example, this should be closed.

[brson]

We should delete the cheatsheet.