rustdoc: add three-column layout for large desktops

[notriddle]

CC @the8472 @GuillaumeGomez

Dependent on #120736

Summary

On very large displays, use a three-column layout, splitting up the TOC and ModNav.

Preview

• http://notriddle.com/rustdoc-html-demo-9/three-column/rust/std/index.html

Motivation

Multiple people have asked for a doc layout that makes better use of the larger screens that Rust development itself is usually done on.

More importantly, people have asked for the navigation aids that rustdoc already has, but buries underneath the list of Methods and such. This is a side-effect of mixing together lateral navigation with the table of contents.

However, there is some nuance to how noticeable the local navigation should be. In particular, local navigation should not be more salient than the global navigation, because, if that happens, users may mistake the local navigation for the global one. Visual hierarchy should reflect information hierarchy.

It's not quite this simple, unfortunately. Because ModNav is loaded by JS, it populates after the TOC, which means if we put it on top we get a content jump. It cannot go above anything else.

The three-column layout avoids this no-no, and also does a better job of communicating the information hierarchy.

• The module navigation is grey in an otherwise-white page, but the floating TOC is not. It's also paired with the logo, while the TOC is paired with the page's name. These are both meant to communicate the difference between the TOC and the ModNav.

• By exposing the ModNav more easily, the You Are Here highlighted item name is more commonly visible. Look at the left sidebar in the screenshot.

  That tabbed-out HashMap struct name under the Structs header under In std::collections is great.

• Also, this is how MDN does it. Presumably, they know what they're doing.

Drawbacks

This is, really, a pretty serious backslide on the decluttering. If someone really needs to get rid of these things, they can. Click the Settings button, the hide the TOC. But that's probably not a great first impression.

Rationale and alternatives

Why is the TOC in a box?

It's a scrollbar thing.

An earlier version of this feature divided the browser into three equally-tall sections. It's the way I wanted the feature to work. But, in doing so, I would have to pick between two bad options for the main document's scrolling behavior:

• To put the scrollbar anywhere other than the rightmost edge of the browser window, the main scrolling area would have to be something other than the body tag. Doing this breaks a bunch of built-in browser behaviors.
• If the scrollbar were put at the far right, it would stack two scrollbars directly beside each other that scroll different things. It would basically break scrolling with the scroll bar.

To side-step this problem, the box helps telegraph what's actually going on. The one inside the box scrolls the box that contains it, while the one outside the box scrolls the page.

Why isn't there a configuration switch to force the one-sidebar view?

Does anybody want this? There's already an option to turn the TOC off entirely, if it's distracting.

Why isn't there a way to resize the TOC box?

It fills all available space. What you'd get would be a way to resize the content area.

Resizing the content area, while it sounds nice, would require a bunch of layout optimization, because right now, resizing it requires too much layout work and is very very slow.

Prior art

This layout is very similar to MDN.

Unresolved questions

• Is this enough to get across to new users the difference between the TOC and the navigation? If not, should we do something like MDN's "In This Article" labeling?
• Should we highlight the currently-visible section in the sidebar, like MDN does? It might act a bit weird, since the Methods section is alphabetical but the page itself is not.

[rustbot]

r? @fmease

rustbot has assigned @fmease.
They will have a look at your PR within the next two weeks and either review your PR or
reassign to another reviewer.

Use r? to explicitly pick a reviewer

[GuillaumeGomez]

The UI is very weird, it adds new lines in the left sidebar and a floating menu on the right. Wouldn't it be possible to not make it stand out as much? Like just having a border on the left and making it take the "full space" on the right and top?

[notriddle]

I'm not sure what to add that I didn't already mention in the Rationale and Alternatives section:

Why is the TOC in a box?

It's a scrollbar thing.

An earlier version of this feature divided the browser into three equally-tall sections. It's the way I wanted the feature to work. But, in doing so, I would have to pick between two bad options for the main document's scrolling behavior:

• To put the scrollbar anywhere other than the rightmost edge of the browser window, the main scrolling area would have to be something other than the body tag. Doing this breaks a bunch of built-in browser behaviors.
• If the scrollbar were put at the far right, it would stack two scrollbars directly beside each other that scroll different things. It would basically break scrolling with the scroll bar.

To side-step this problem, the box helps telegraph what's actually going on. The one inside the box scrolls the box that contains it, while the one outside the box scrolls the page.

The line in the left sidebar could be removed, but is mostly meant to work like the one in the Source Files viewer, since its scroll behavior is the same.

[GuillaumeGomez]

Isn't it possible to "cheat" in order to make it look like a plain sidebar while keeping it in the same scroll interactions?

[the8472]

If the scrollbar were put at the far right, it would stack two scrollbars directly beside each other that scroll different things. It would basically break scrolling with the scroll bar.

You could hide the scollbar of the sidebar and then manually scroll it via javascript to keep it in sync with the section the main page is showing. This would only be necessary if the TOC is longer than a screen height anyway.

[GuillaumeGomez]

If the scrollbar were put at the far right, it would stack two scrollbars directly beside each other that scroll different things. It would basically break scrolling with the scroll bar.

You could hide the scollbar of the sidebar and then manually scroll it via javascript to keep it in sync with the section the main page is showing. This would only be necessary if the TOC is longer than a screen height anyway.

Let's not. The content of the TOC can be part of the main page (so sharing the same scroll).

[notriddle]

The content of the TOC can be part of the main page (so sharing the same scroll).

Are you thinking of having it work like this?

Screencast.from.2024-02-12.10-31-32.webm

I'm not sure that's useful. The page is so much longer than the TOC. If you click anything in the TOC, it's basically guaranteed to disappear, and you have to scroll back to the top to get to it.

This would only be necessary if the TOC is longer than a screen height anyway.

That doesn't seem unusual, since trait implementations and methods are listed in there.

That's not a SpidersGeorg type. Those are all very basic, normall error-ish trait implementations, and there's enough of them to fill the page.

[the8472]

Yeah I think vertical menus that only show the name and nothing else just take up way too much space for the limited value they provide. They just don't strike the right balance imo.
Yes, there are cases where one just wants to jump to a method or impl by name and in those cases they do the job, especially when they're the first hit via Ctrl+F.

But if one doesn't already know what one is looking for then a summary that's more verbose than just the name but more concise than the full docs would help.

For an alternative design look at javadocs.

For interfaces they have a horizontal list: https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Map.html
Additionally they have summary tables (with a responsive design, that reflows at <800px): https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Map.html#method-summary

I'm not saying javadocs strike the perfect balance on everything, but imo in at least those two aspects they're doing better than rustdoc

[fmease]

I haven't reviewed this yet because I'm assuming this is effectively S-waiting-on-team Status: Awaiting decision from the relevant subteam (see the T-<team> label). . If that's not the case, I can gladly review it.

[bors]

☔ The latest upstream changes (presumably #123725) made this pull request unmergeable. Please resolve the merge conflicts.