let rustdoc print the crate version into docs

[QuietMisdreavus]

This PR adds a new unstable flag to rustdoc, --crate-version, which when present will add a new entry to the sidebar of the root module, printing the given version number:

Closes #24336

(The WIP status is because i don't want to merge this until i can get the std docs to use it, which i need help from rustbuild people to make sure i get right.)

[rust-highfive]

Some changes occurred in HTML/CSS.

cc @GuillaumeGomez

[rust-highfive]

r? @steveklabnik

(rust_highfive has picked a reviewer for you, use r? to override)

[QuietMisdreavus]

Pings for everyone!

@rust-lang/docs Does this look right? Is this a good place for this? Right now it only shows up on the root module's page - nothing else will show this. Should we put it everywhere?

@GuillaumeGomez and @steveklabnik specifically (possibly dev-tools more broadly, but for now i'll stick with rustdoc peers) - This is a new command-line flag. In dev-tools meeting today the prevailing air was that this was not RFC worthy since it was straightforward enough, but i want to make extra sure that the other rustdoc stakeholders are on board.

@alexcrichton @Mark-Simulacrum (other rustbuild experts?) - How can I get bootstrap to use this flag when rendering docs for std and friends?

[GuillaumeGomez]

Seems to be good. What happens with a very long version name? Does it goes on two lines or does it just stick out of the sidebar?

[QuietMisdreavus]

Looks like it wraps within the sidebar:

...unless you use a long word without a breaking separator, in which case it sticks out from the sidebar:

[GuillaumeGomez]

This is a (smaaall) bug then. :p

[steveklabnik]

This sounds good to me!

[camsteffen]

Use these styles to fix the wrapping issue on most modern browsers.

overflow-wrap: break-word;
word-wrap: break-word; /* deprecated */
word-break: break-word; /* Chrome, non-standard */

[QuietMisdreavus]

Wow, thanks! That looks much better!

I've force-pushed to include that CSS into the update.

[GuillaumeGomez]

Now it's all good. Thanks!

@bors: r+ rollup

[bors]

📋 Looks like this PR is still in progress, ignoring approval

[GuillaumeGomez]

Ah damn, well, r=me once done.

[QuietMisdreavus]

Yeah, the rustdoc piece is basically done, but i'd like to see if i can get rustbuild to use this when generating the docs for std and friends before calling it done. I'll ask around again.

[Mark-Simulacrum]

You'll need to edit src/bootstrap/builder.rs and add RUSTDOC_CRATE_VERSION to the rustdoc_cmd environment variables. The value can be pulled from channel::CFG_RELEASE_NUM (1.22.0) or if you want the SHA, self.build.rust_info.version(...) will work.

Let me know if you'd like more detailed instructions, or I can probably get you a commit implementing this within a few days.

[QuietMisdreavus]

@Mark-Simulacrum That got me most of the way there. It turns out that the docs weren't using rustdoc_cmd at all, instead going through cargo. I wound up adding RUSTDOCFLAGS to each doc invocation to get the crate version in, but that can introduce problems in compiler-docs mode, since external crates will also get that version number. I also don't know how this will interact if/when Cargo starts providing this flag itself, but for the moment this does what i want:

If you think this is fine, then i'm ready to call this good.

[Mark-Simulacrum]

Hm, I'm suspecting that RUSTDOCFLAGS may not apply correctly with compiler docs, since we want the version to display on more than just the last crate. I think I'd move to unconditionally setting something like RUSTDOC_CRATE_VERSION in cargo (src/bootstrap/builder.rs) and then using that in src/bin/rustdoc.rs to set the unstable option.

[QuietMisdreavus]

Ooh, i like that option. I've force-pushed with an update that uses that instead.

[Mark-Simulacrum]

I'm happy with the rustbuild changes after this small nit.

[Mark-Simulacrum]

I'm happy with the rustbuild changes after this small nit.

[Mark-Simulacrum]

Let's also add this to rustdoc_cmd above to make certain it's passed in all cases.

[QuietMisdreavus]

Force-pushed with this update.

[Mark-Simulacrum]

@bors r=GuillaumeGomez

[bors]

📌 Commit 7ea286e has been approved by GuillaumeGomez