Run doc tests on README

[huonw]

cargo test could run (the equivalent of) rustdoc --test README.md, since people often have a basic example in it.

See also

• cargo doc could support building/testing standalone markdown files #739
• doc-comment
• cargo-readme

Past efforts

• Run doc tests over the README if present #445

[tomjakubowski]

I imagine people might have many markdown files which are documentation and contain examples; it would be nice to be able to specify additional .md files to run rustdoc --test on in Cargo.toml.

[alexcrichton]

Sounds like a good idea! We could at least start out with a README and expand it with a manifest key later on.

[alexcrichton]

Some concerns were raised in #445 which are applicable to this as well.

[tomaka]

The question is: how will README interact with the Cargo registry?

Currently the examples are in the README file mainly because it's easy to read when you discover a library on github.

But if the registry automatically provides the rustdoc output of each package, then I think that the basic examples should simply be in the crate root documentation, just like the standard regex and green crates do.

[skade]

I'd like to have this feature. Broken README code is worse then broken code in the crate docs, as this is the first place where people go to. Outdated READMEs are even worse of an issue, a thing tested READMEs elegantly circumvent.

Also, I prefer writing README code, as crate documentation is a bit cumbersume and hard to read in source, given the amount of comment characters it needs.

Rust code can be highlighted on github and ignored by using:

   ```{.rust .ignore}

(this currently is parsed correctly, but not properly picked up. {.ignore .rust} works. I'll file a bug on rustdoc after validating)

As a middleground, my suggestion is to allow listing additional documents to test with rustdoc in the Manifest and generate a Cargo.toml including "README.md" in that list per default. This raises awareness of the feature, but ultimately leaves the user in control.

[skade]

I'd like to push this one, I just ran into precisely the problem that my README examples were the only ones broken.

[pzol]

+1

[pythonesque]

I would love this.

Concerns can be addressed by making the feature opt-in (and maybe also with attribute metadata, but I don't know markdown well enough to know if that's a thing).

[moonglum]

👍

[s-panferov]

Always forget to update README.md in my projects 👍

[huonw]

cc https://github.com/brson/rust-skeptic