rustdoc: add --minimum-supported-rust-version option

[GuillaumeGomez]

The end goal is of course to make cargo directly pass this option to rustdoc based on its rust-version field.

It currently looks like this:

cc @Manishearth
r? @jsha

[rust-highfive]

Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez,@Folyd,@jsha

[Manishearth]

Is this on every page or just the crate root? I'm not sure if it should be prominently on every page

[GuillaumeGomez]

Only the crate root. I added a test to ensure it was only there too here. I also think that it should be only on the crate page (@jsha seems to agree too based on the zulip discussion).

[notriddle]

In short, I'm against this. It seems like you're choosing to make the MSRV the most prominently-shown dependency of a crate because of how easy it is to do, instead of choosing to make the most important dependency the prominent one.

The Rust compiler dependency is the least important dependency, because we ($DAYJOB) aren't actually shipping the compiler (except libstd, I suppose), and because upgrading the compiler is generally quite safe. The compiler itself only matters to our devops people and customers as long as it can produce binaries that run on an LTS build of Ubuntu Server and all currently-supported versions of Windows, which have never been a problem. Bumping the compiler version just works every time we've done it, thanks to the Rust Project's terrific quality control.

The same cannot be said for every random crate you find on crates.io. Those are the dependencies we actually care about, because we need to vet them ourselves, and know enough about what they do to be able to fork them or switch away from them if something happens. Cargo makes it easy to add crate dependencies, but it doesn't actually solve the QA problems. cargo tree is really nice; it should be official.

The most important dependency, for many projects, is the list of supported operating systems. More often than not, you're locked into a particular OS, and a crate that fails to support it is an instant deal-breaker. Our customers overwhelmingly use Windows workstations, while we deploy Linux servers, and no crate is valuable enough to be worth switching.

In short, when evaluating a crate, the dependencies I actually care about are, in order: supported OS, required C libraries, required Rust libraries, and finally MSRV.

[Manishearth]

Honestly I kinda feel like it should be a part of the docs.rs ribbon UI biut otherwise not in rustdoc. But I'd like to hear from @jsha

[GuillaumeGomez]

The problem is that not crates use docs.rs for their documentation (cc gtk-rs), so if it's on docs.rs, why not directly in rustdoc? But @notriddle's arguments against it make sense too.

[Manishearth]

@GuillaumeGomez Right, I know, but balanced against notriddle's concerns, I feel like docs.rs is a place where we can solve this problem 99% of the time without hitting the same concerns.

People generating their own docs can also do something similar to docs.rs and embed them with a header. I do not think we should offer everything people may want in their own docs as a feature.

[GuillaumeGomez]

Let's close it for the time being then. :)

[jsha]

I'm in agreement with @notriddle and @Manishearth. I think @notriddle expressed it quite well, but to add my own words:

This is useful information, and is thematically very similar to the rest of the information on the crate page on docs.rs (https://docs.rs/crate/rustls/latest): features, homepage, repository, dependencies, README. All of this stuff is available at rustdoc build time. In theory rustdoc could generate that page; as far as I know it's an accident of implementation that docs.rs generates it instead of rustdoc.

I see your point about self-hosted rustdoc instances like https://docs.serde.rs/ and https://gtk-rs.org/gtk-rs-core/stable/latest/docs/glib/index.html. But I think focusing on MSRV misses the point. Self-hosted rustdoc would benefit from having all the information from the crate page on docs.rs. And some of that information is much more useful and important than MSRV. If we want to make self-hosted docs more informative, let's make that a project, to reproduce the crate page from docs.rs (and maybe docs.rs could then phase out its version?). It still might not be a huge priority, but I think that's a more sensible place to put MSRV.