Fix documentation for package.readme option.

[fa7ca7]

Fix for #4620.

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @matklad (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[matklad]

LGTM!

But I am not sure if this has to be updated in both paces :(

@behnam could you explain a bit how this whole mdBook thing works for Cargo docs, and what files should be modified when one wants to update the docs?

[behnam]

Uh, sorry for the delay. Just got to this in the inbox queue.

The diff looks good, as have edited both copies of the doc, which is what we need right now. (Until we drop the non-mdBook copies and kill docs.crates.io.)

@matklad, I've tried to explain the current situation in src/doc/README.md:

NOTE: Cargo documentation is under migration to mdBook-based structure. All the
*.md files here shall be kept in sync with the *.md files under book/src/.
See MIGRATION_MAP file here and #4453
for details.

Do you think there's a need to add more details to the note to help with future patches/reviews?

[matklad]

@behnam thanks, I'vecomoletelly missed the whole thing, including src/doc/read me!

@bors r+

[bors]

📌 Commit 5ccf654 has been approved by matklad

[bors]

⌛ Testing commit 5ccf654 with merge b3ba626...

[bors]

☀️ Test successful - status-appveyor, status-travis
Approved by: matklad
Pushing b3ba626 to master...

[kbknapp]

@dethoter or @matklad

I'm trying to find out about clap-rs/clap#1186 if I have a large README.md and it's listed in the cargo readme = "..." but also listed in the exclude = [...] array, will my readme still get rendered on crates.io?

[behnam]

I don't think so, @kbknapp, because the README.md file won't be in the package submitted to crates.io. So, crates.io will be trying to access your readme file, but would fail.

You should be able to test it by cargo package and then see if the file is included.

Do you think the file assigned by package.readme setting, and similar files like Cargo.toml itself, should be exceptions in exclusion and always included?

/cc @alexcrichton

[sfackler]

The easiest thing to do is to symlink the readme into the subdirectory. The readme will be inlined when the crate is packaged.