Add documentation for docs.rs metadata

[Stargateur]

A question pop on stackoverflow today asking about how one could build the doc when build.rs fail because there is not the lib needed to link. The lib should not be needed for a doc build so the question ask about how we could skip the build script somehow.

The solution exist but it's very poorly documented, in the about page ! And https://doc.rust-lang.org/cargo/commands/cargo-metadata.html or https://doc.rust-lang.org/cargo/reference/manifest.html#package-metadata doesn't do better. Would be nice if someone who write better English than me write some doc for it.

Note: I'm surprise this go behind metadata, in my opinion metadata should not affect build, well, this too could be clarify.

rust-lang/rust-playground#192

[epage]

What do people think of cross-linking the metadata table docs to https://docs.rs/about/metadata?

The main concern I can think of is the slippery slope of what all should be cross-linked. I'd limit it to official Rust projects, like docs.rs, the line distinguishing the individual parts is blurred. When more explicitly dealing with an external process, like cargo-releases package.metadata.release, its more obvious that where to look for the documentation.

[Stargateur]

wow 3 years It feel it someone else that open this issue. I updated the SO question with what docs.io advice in 2022 so now maybe add a link on build page that link to https://docs.rs/about/builds is better.

But metadata page of cargo could also use a link to the metadata table of docs.io

[ehuss]

I think it would be great to link to the documentation of docs.rs. Linking to other rust-lang projects is fine.

I know for myself, it still takes me a while to find the docs.rs docs, and I've seen them many times. They do seem to be somewhat hidden.

I'm not sure exactly where to link it. As mentioned, there are multiple points of interaction (metadata table, cargo doc, build scripts, publishing, etc.), and I'd be cautious to emphasize it in too many places. Sorry that isn't too constructive. I'd suggest picking a couple different places where you think it seems like it would be likely to be discovered and found.

[epage]

Probably the link we added in #12879 is sufficient.