doc: how to run examples

[coolaj86]

Newbie Rusties, Mob programming live right now to figure this out:
https://www.youtube.com/watch?v=xu2r8tuUs6k

[mrobinson]

First off, thank you for the contribution.

This is the standard way of running examples in a rust project, so I'm inclined to close this. It would really only be useful if it differed somehow from a typical rust project.

[coolaj86]

Most projects definitely do not have cargo run --example print-rcdom.

There's no way anyone would know to do this to check that things build correctly without being familiar with this project.

Nor do most devs even know that git submodules exist (all that mono repo hype).

And giving someone the copy / paste for "how to download, install, and experience this" is just a nice thing to do.

This is project is very niche and many of the people who find it are going to be non-experts, just experimenting with things (by definition, since the majority of experts already have solutions that work for them).

So although, yes, obviously if you know you know, I think there's a lot of value here at no tangible cost - helps some, hurts none.

And we did have experienced Rust developers in our group. It still took a bit to figure out what to do.

That said, at the very least there's some documentation here for someone coming across this in the future.

[mrobinson]

There are instructions for initializing the git submodules in this repository in the top-level README (https://github.com/servo/html5ever#working-on-html5ever). Perhaps this could be made more prominent, but in general I think we shouldn't be repeating ourselves too much in the documentation. In addition, it's not very scalable for every Cargo-based project to document how to use Cargo (https://doc.rust-lang.org/cargo/commands/cargo-run.html#examples).

[mrobinson]

That said, a line showing how to run all examples in the top-level README is probably fine.