Native support for docs.rs conditional compilation

[epage]

Currently, docs.rs sets DOCS_RS on the environment of the build which allows build scripts to tell when running within docs.rs but this requires users to add boilerplate if they want to then use unstable features for the docs.

#954 codified in the documentation a practice of having --cfg docsrs set in the metadata table.

This pattern has been long enough that it seems like we should just bake it in and always pass --cfg docsrs for users. This would be both a code to pass in the flag like the user does today and a documentation update.

One reason to do something is to help break a deadlock on a problem with --check-cfg. If Cargo passes --check-cfg to rustc by default, then instances of #[cfg(docsrs)] will warn.

• You can't put an #[allow] around a #[cfg]
• You could put it in the enclosing scope but, for enabling nightly features, that would be the entire lib, negating this feature
• You could add a build.rs to tell cargo that docsrs is a "known value" but that then slows down your build for documentation and increases boilerplate
• You could use a Cargo feature instead but having nightly-only features is annoying (no cargo check --all-features).

rustc --check-cfg has a list of well-known names but

• docs.rs might be removed enough from rustc that it might not make sense to bake in docs.rs-specific logic. We could solve this by having the concept of well-known names in Cargo which has a closer relationship with docs.rs.
• Even if we do, its a convention, rather than a policy of docs.rs. If docs.rs/ passed in --cfg docsrs, then it adds weight for making it a well known name.

A future extension of this could be to set a different --cfg for public dependencies of what is being built

zulip thread