Run doc tests over the README if present

[alexcrichton]

The default path to the readme is README.md, and this can be overridden with
the readme key in the project manifest. A value of false will disable
documentation tests, while a string value will be considered the relative path
to the readme.

Closes #383

[tomaka]

I'm not sure that this is a good idea.

This will fail: https://github.com/bjz/gl-rs/blob/master/README.md
This will fail: https://github.com/tomaka/rust-hl-lua/blob/master/README.md
This will fail: https://github.com/PistonDevelopers/rust-image
etc.

In regular documentation you can fix this by having ````ignoreor by adding hidden lines with a#` prefix, but this is not desirable in a README file because it makes the file more difficult to read (example).

A lot of repositories will probably choose between removing all code from their README or disable this feature.

[brson]

I'm also a bit skeptical of this.

[alexcrichton]

Hm ok, I think we'll need to think more closely about this feature.

[WaffleLapkin]

In regular documentation you can fix this by having ```ignore or by adding hidden lines with a # prefix, but this is not desirable in a README file because it makes the file more difficult to read (example).

Actually you could write

```rust,ignore

This will be understood by both rustdoc and github

[tim-weis]

I'm not sure that this is a good idea.

This will fail: https://github.com/bjz/gl-rs/blob/master/README.md
This will fail: https://github.com/tomaka/rust-hl-lua/blob/master/README.md
This will fail: https://github.com/PistonDevelopers/rust-image etc.

In regular documentation you can fix this by having ````ignoreor by adding hidden lines with a#` prefix, but this is not desirable in a README file because it makes the file more difficult to read (example).

A lot of repositories will probably choose between removing all code from their README or disable this feature.

It's been 8 years. Are those concerns still valid, or is it time to progress along with common practice? I'd love to see some tentative (or aggressive, even) exploration on this.

What are the specific issues inhibiting progress on this?

[WaffleLapkin]

The ignore concern I believe is not valid anymore, as noted in #445 (comment). # is not understood by github the same way it is used by rustdoc (hiding lines) though, so to be able to use this feature you'll need to make the examples complete, for better or worse.

I don't think this can be added as a default behavior, but as an opt-in I think this is sensible.