rustdoc: show crate name beside smaller logo

[notriddle]

Blocked on rust-lang/cargo#12800

Summary

In this PR, the crate name and version are always shown in the sidebar, even in subpages, and the lateral navigation is always shown in the sidebar, even in modules.

Clicking the crate name does the same thing clicking the logo always did: take you to the crate root (the crate's home page, at least within Rustdoc).

The Rust logo is also no longer shown by default for non-Rust docs.

Screenshots

Before

	Macro	Module
In crate
In module1

Whole sidebar screenshots

	Macro	Module
In crate
In module

Different logo configurations

	Short crate name	Long crate name
Root
Subpage

Without a logo

Preview pages

https://notriddle.com/rustdoc-html-demo-5/sidebar-layout-rocket/rocket/index.html

https://notriddle.com/rustdoc-html-demo-5/sidebar-layout-rocket/rocket_sync_db_pools/index.html

https://notriddle.com/rustdoc-html-demo-5/sidebar-layout-rust-compiler/index.html

https://notriddle.com/rustdoc-html-demo-5/sidebar-layout-rust/std/index.html

https://notriddle.com/rustdoc-html-demo-5/sidebar-layout-rocket/tokio/index.html

Motivation

This improves visual information density (the construct with the logo and crate name is shorter than the logo on its own, because it's not square) and navigation clarity (we can now see what clicking the Rust logo does, specifically).

Compare this with the layout at Phoenix's Hexdocs (which is what this proposal is closely based on), the old proposal on Internals Discourse (which always says "Rust standard library" in the sidebar, but doesn't do the side-by-side layout).

Guide-level explanation

This PR cleans up some of the sidebar navigation.

It makes the logo in the desktop sidebar a bit smaller, and puts the crate name and version next to it (either beside it, or below it, depending on if there's space), making it clearer what clicking on it does: click the crate name to open the crate's home page. It also removes the Rust logo from non-official-Rust crates, again to make the navigation and supply chain clearer (since the crate name has been added, the logo is no longer necessary for navigation).

It adds a bit more clarifying information for lateral navigation. On items that don't add their own sidebar items, it just shows its siblings directly below the crate name and logo, but for other items, it shows "In crate alloc" instead of just "In alloc". It also shows the lateral navigation tools on module pages, making modules consistent with every other item.

Drawbacks

While this actually takes up less screen real estate than the old layout on desktop, it takes up more HTML. It's also a bit more visually complex.

Rationale and alternatives

I could do what the Internals POC did and keep the vertically stacked layout all the time, instead of doing a horizontal stack where possible. It would take up more screen real estate, though.

Prior art

This design is lifted almost verbatim from Hexdocs. It seems to work for them. opentelemetry_process_propagator, for example, has a long application name.

Unresolved questions

Maybe we should encourage crate authors to include their own logo more often? It certainly helps give people a better sense of "place." This seems to be blocked on coming up with an API to do it without requiring them to host the file somewhere.

Future possibilities

Beyond this, plenty of other changes could be made to improve the layout, like

• Fix things so that clicking an item in the sidebar doesn't cause it to scroll back to the top.
  • The Internals demo does this right: clicking an item in the sidebar changes the content area, but the sidebar itself does not change. This is nice, because clicking is cheap and I can skim the opening few paragraphs while browsing.
  • The layout of the docs sidebar causes trouble to implement this, because it's different on different pages, but at least fix this on the file browser.
• Come up with a less cluttered way to do disclosure. There's a lot of [-] on the page.
  • We don't lack ideas to fix this one. We have too many.
• Do a better job of separating local navigation (vec::Vec links to vec::IntoIter) and the table of contents (vec::Vec links to vec::Vec::new).
  • A possibility: add a Back arrow next to the "In [module]" header?
    
• Give readers more control of how much rustdoc shows them, and giving doc authors more control of how much it generates. Basically, rustdoc: allow resizing the sidebar / hiding the top bar #115660 is great, let's do it too.

But those are mostly orthogonal, not future possibilities unlocked by this change.

Footnotes

1. This PR also includes a bug fix for derive macros not showing up in the lateral navigation part of the sidebar ↩

[rustbot]

r? @fmease

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

[rustbot]

Some changes occurred in GUI tests.

cc @GuillaumeGomez

Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez, @jsha

[rustbot]

Some changes occurred in GUI tests.

cc @GuillaumeGomez

Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez, @jsha

[GuillaumeGomez]

I really like when the name is small and right beside the logo. But for the rest, no opinion. I'm not sure removing Crate from the text is a good idea too (for long names).

[notriddle]

But for the rest, no opinion. I'm not sure removing Crate from the text is a good idea too (for long names).

AFAIK, there isn't any way to make the text different for short or long names, because that's dependent on typesetting information that librustdoc doesn't have. The layout shift is done using frontend CSS, limiting how elaborate I can get.

I'm not sure it's a good idea to have the word "Crate" there, anyway. It made some sense when the crate wasn't always present, but if this part of the sidebar is going to be persistent, then we probably want it to be terse so it doesn't take up too much space.

I really like when the name is small and right beside the logo.

It definitely looks good on the standard library. It's especially helpful because it gives a perpetual version indicator, even when not on the crate root page,

For non-standard library crates, I'd really like to know if there's a written rationale for having the Rust logo there. If it's just a matter of wanting a link to the crate root page, then this PR can just remove it and save the screen real estate and the bandwidth.

[fmease]

If we turned it off on non-standard crates by default, it would line wrap crate names a lot less often.

For non-standard library crates, I'd really like to know if there's a written rationale for having the Rust logo there.

Personally speaking, I'd be in favor of dropping the Rust logo in those cases. I bet it takes a bit of digging to find the PR that introduced this. It probably goes all the way back to the pre-1.0 days.

it would line wrap crate names a lot less often

We could also experiment with inserting <wbr>s after underscores in crate names (or any identifier actually) which might lead to more legible output, although that's probably outside the scope of this PR.

I'm not sure it's a good idea to have the word "Crate" there, anyway. It made some sense when the crate wasn't always present, but if this part of the sidebar is going to be persistent, then we probably want it to be terse so it doesn't take up too much space.

Agreed.

---

I haven't looked into the finicky bits of the implementation yet (like all those negative margins) but generally it looks reasonable.

[rustbot]

This PR changes Stable MIR

cc @oli-obk, @celinval, @spastorino

[fmease]

Theoretically, you could've updated the Cargo tests directly through the git submodule src/tools/cargo which is part of this repo if I'm not mistaken instead of opening a PR over at rust-lang/cargo.

[notriddle]

@bors r=fmease

[bors]

📌 Commit 8222335 has been approved by fmease

It is now in the queue for this repository.

[bors]

⌛ Testing commit 8222335 with merge 6d05c43...

[bors]

☀️ Test successful - checks-actions
Approved by: fmease
Pushing 6d05c43 to master...

[rust-timer]

Finished benchmarking commit (6d05c43): comparison URL.

Overall result: ✅ improvements - no action needed

@rustbot label: -perf-regression

Instruction count

This is a highly reliable metric that was used to determine the overall result at the top of this comment.

	mean	range	count
Regressions ❌ (primary)	-	-	0
Regressions ❌ (secondary)	-	-	0
Improvements ✅ (primary)	-0.4%	[-0.4%, -0.4%]	1
Improvements ✅ (secondary)	-0.5%	[-0.5%, -0.5%]	1
All ❌✅ (primary)	-0.4%	[-0.4%, -0.4%]	1

Max RSS (memory usage)

Results

This is a less reliable metric that may be of interest but was not used to determine the overall result at the top of this comment.

	mean	range	count
Regressions ❌ (primary)	2.4%	[1.9%, 2.9%]	2
Regressions ❌ (secondary)	2.1%	[0.9%, 5.1%]	6
Improvements ✅ (primary)	-	-	0
Improvements ✅ (secondary)	-1.7%	[-2.6%, -1.4%]	4
All ❌✅ (primary)	2.4%	[1.9%, 2.9%]	2

Cycles

This benchmark run did not return any relevant results for this metric.

Binary size

This benchmark run did not return any relevant results for this metric.

Bootstrap: 626.975s -> 627.49s (0.08%)
Artifact size: 271.30 MiB -> 271.28 MiB (-0.01%)

[Veykril]

// We want to be able to build this crate with a stable compiler, so no
// `#![feature]` attributes should be added.

This broke the crate on stable

[fmease]

Oof, sorry. I absolutely missed that while reviewing. I'm gonna open a PR later. Are there projects which are already affected by this? r-a? Should I nominate that PR for any backports (none, beta, beta+stable)?

[Veykril]

No need for backports, anyone relying on these via rustc_private are required to be on nightly anyways. This was merely noticed in r-a when we wanted to bump our autopublished copy, so no rush.

[Veykril]

For crates like these it'd be nice if there was a #[forbid(feature_attribute)] lint or something

[lnicola]

I don't think this happened yet? Can I just delete the three lines?