rustdoc: Please process top-level README by default

[ijackson]

gitlab and crates.io both like to render the toplevel README (normally for a Rust crate, README.md). rustdoc formats crate-level documentation in src/lib.rs.

The result is that for many crates, the README contains very useful documentation not replicated in the rustdoc. For example, an introduction, or usage notes.

But, anomalously, that information is not shown at docs.rs and nor is included in rustdoc output.

This is confusing, because it means that when browsing crates online, the link in crates.io to "documentation" goes to a site which somehow doesn't have the documentation one was just looking at!

And it is a serious nuisance if one is using cargo doc to generate a documentation set for working offline: the resulting documentation is missing important parts.

I found #44732 and #66249 which seem to be related. In this issue I'm asking that README.md should be processed by default, and put somewhere prominent in the rustdoc output.

[jyn514]

that information is not shown at docs.rs

It's shown on the /crate page (which I understand no one visits).

[ijackson]

Joshua Nelson writes ("Re: [rust-lang/rust] rustdoc: Please process top-level README by default (#76966)"):

that information is not shown at docs.rs It's shown on the /crate page (which I understand no one visits).

Here is an example: https://docs.rs/ambassador/0.2.1/ambassador/ https://github.com/hobofan/ambassador I'm not sure exactly what you mean by "the /crate page". I tried various URLs which seemed like they might be what you meant without any luck. Is the page you are referring to generated by rustdoc or by docs.rs ? Ian.

…

-- Ian Jackson <ijackson@chiark.greenend.org.uk> These opinions are my own. Pronouns: they/he. If I emailed you from @fyvzl.net or @evade.org.uk, that is a private address which bypasses my fierce spamfilter.

[jyn514]

The readme for that crate is shown here: https://docs.rs/crate/ambassador/0.2.1

[jyn514]

Is the page you are referring to generated by rustdoc or by docs.rs ?

It's generated by docs.rs, not rustdoc.

[ijackson]

Joshua Nelson writes ("Re: [rust-lang/rust] rustdoc: Please process top-level README by default (#76966)"):

The readme for that crate is shown here: https://docs.rs/crate/ambassador/0.2.1

Oh so it is! I still think it would be good for there to be a way to get it from rustdoc. Hopefully usefully linked into the other rustdoc-generated pages. Thanks, Ian.

…

-- Ian Jackson <ijackson@chiark.greenend.org.uk> These opinions are my own. Pronouns: they/he. If I emailed you from @fyvzl.net or @evade.org.uk, that is a private address which bypasses my fierce spamfilter.

[peterjoel]

I would like to do something like:

#![doc(path = "../README.md")]

[jyn514]

@peterjoel on nightly you can use doc = include_str!("README.md"): #78835

[peterjoel]

@jyn514 Thanks! I hadn't seen that RFC

[newpavlov]

doc = include_str! is stabilized and widely used in the ecosystem. I think this issue can be closed?

[ijackson]

doc = include_str! is stabilized and widely used in the ecosystem. I think this issue can be closed?

Well, I think it would be better if you didn't have to put a piece of boilerplate at the top of every package.

Such a transition could be done in an edition, maybe.

[newpavlov]

It would be a highly intrusive change. I think at the very least it requires an RFC, not this issue.