Simplify and unify rustdoc sidebar styles #92692

jsha · 2022-01-09T14:50:55Z

This switches to just use size, weight, and spacing to distinguish headings in the sidebar. We no longer use boxes, horizontal bars, or centering to distinguish headings. This makes it much easier to understand the hierarchy of headings, and reduces visual noise.

I also refactored how the mobile topbar works. Previously, we tried to shift around elements from the sidebar to make the topbar. Now, the topbar gets its own elements, which can be styled on their own. This makes styling and reasoning about those elements simpler.

Because the heading font sizes are bigger, increase the sidebar width slightly.

As a very minor change, removed version from the "All types" page. It's now only on the crate page.

r? @GuillaumeGomez
cc @camelid
Discussed on Zulip.

Note: This has a lot of smaller commits, but I plan to squash them before merging.

rust-highfive · 2022-01-09T14:50:58Z

Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez,@Folyd

src/librustdoc/html/render/mod.rs

GuillaumeGomez · 2022-01-09T15:18:10Z

Wouldn't it be better to have the current item name in the sidebar use the color of its type? Because it's currently difficult to make the difference between this one and the other titles. A screenshot:

GuillaumeGomez · 2022-01-09T15:20:04Z

It'd be nice to change the display of the version because currently it's absolutely the same as the other links in the sidebar:

src/librustdoc/html/render/mod.rs

GuillaumeGomez · 2022-01-09T15:23:06Z

The burger button is displayed weirdly and is too small I think:

Also, the whole header now remains displayed all the time, which is a loss of space. Not sure it's a good idea...

EDIT: The source file viewer sidebar is completely broken currently too.

GuillaumeGomez · 2022-01-09T15:25:28Z

Overall I really like the direction it's taking though. The sidebar looks much cleaner. I don't think you should unify it with the source file viewer sidebar though. They have both very different meaning after all.

GuillaumeGomez · 2022-01-09T15:34:34Z

When the item name is too long, the sidebar gets a "x scrollbar":

Also, If the name is too long, wouldn't it be better to break it instead? For methods I think it's fine, but for types it seems weird. Even more considering how little letters can be displayed otherwise...

jsha · 2022-01-09T15:57:38Z

[on mobile] Also, the whole header now remains displayed all the time, which is a loss of space. Not sure it's a good idea...

I think it's a distinctly good idea. The current design, where only the hamburger menu floats along with the page, feels very broken to me. And it doesn't make the top 45px usable because it overlaps with some of the body text. Also, the topbar provides useful context about where you are, and quick click targets to go to the root of the module (and, later, to the top of the page - which I'd like to add in a separate PR).

jsha · 2022-01-09T18:28:37Z

The current design, where only the hamburger menu floats along with the page, feels very broken to me. And it doesn't make the top 45px usable because it overlaps with some of the body text.

To put this another way: We should either have a topbar that doesn't follow the scroll, or we should have a topbar where the whole width of it follows the scroll. The current situation, where just the hamburger part of the topbar follows the scroll, is unusual UI and doesn't actually get us more usable viewport.

The source file viewer sidebar is completely broken currently too.

What platform, and what page? I checked on both mobile and desktop, and it looks right to me. Did you hard-reload?

It'd be nice to change the display of the version because currently it's absolutely the same as the other links in the sidebar:

In dark mode and ayu, I had forgotten to change the display of links to get the link color. Now the version is distinguished from the links.

Wouldn't it be better to have the current item name in the sidebar use the color of its type? Because it's currently difficult to make the difference between this one and the other titles.

I tried that earlier. It was cool, but in the end I found that it drew too much attention to the sidebar, when the attention should be on the main content. I'll try to distinguish this with better spacing.

The sidebar looks much cleaner. I don't think you should unify it with the source file viewer sidebar though. They have both very different meaning after all.

Yes, my goal was not to touch the source view sidebar in this PR (though I think it could use some touch-ups too).

The burger button is displayed weirdly and is too small I think:

I've confirmed this in Firefox and will fix.

camelid · 2022-01-09T19:07:37Z

@jsha please rebase instead of merging ;)

jsha · 2022-01-10T01:21:59Z

Alright, I've fixed the source sidebar and the hamburger menu in Firefox Mobile. I also made it so a long item name gets wrapped, and cleaned up some dead code. Updated the demo.

camelid · 2022-01-10T01:51:34Z

@jsha what do you think about #92692 (comment)?

GuillaumeGomez · 2022-01-12T09:25:01Z

What platform, and what page? I checked on both mobile and desktop, and it looks right to me. Did you hard-reload?

All source pages on desktop firefox. It was very likely because of the interactions with the hamburger button. It's working fine now. I should have recorded a video, that would helped to see better the issue...

Also, the topbar provides useful context about where you are, and quick click targets to go to the root of the module (and, later, to the top of the page - which I'd like to add in a separate PR).

I'm not sure what you by this but as always, very curious of what you have in mind. :)

Might be a good idea to add some space after the version number to make "all items" easier to see, no?

In dark mode and ayu, I had forgotten to change the display of links to get the link color. Now the version is distinguished from the links.

👍

I tried that earlier. It was cool, but in the end I found that it drew too much attention to the sidebar, when the attention should be on the main content. I'll try to distinguish this with better spacing.

Much better indeed!

Yes, my goal was not to touch the source view sidebar in this PR (though I think it could use some touch-ups too).

I confirm that the sidebar "header" was removed on the source pages. 👍

Once you're done with the changes, please add GUI tests for the following things:

colors of the items in the sidebar
That for long item name, it doesn't add a scrollbar
That the sidebar header is displayed (or not displayed in the case of source pages) and is working as expected on mobile.

And I think that's it? I really can't wait to have all these improvements merged! :D

bors · 2022-01-13T04:06:23Z

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

jsha · 2022-01-13T16:39:37Z

Rebased, squashed, and pushed the demo. I think all concerns have been addressed.

GuillaumeGomez · 2022-01-14T09:51:13Z

The font size for the source code pages sidebar has been reduced:

On current nightly:

On your PR:

Is it expected? In any case, could you add a test to check the font size in the source code sidebar please?

There is margin on the right in mobile when a link is hovered/selected:

Is it voluntary?

src/librustdoc/html/static/js/main.js

src/test/rustdoc/cap-lints.rs

jsha · 2022-01-18T04:11:45Z

@bors r=GuillaumeGomez rollup

bors · 2022-01-18T04:11:46Z

📌 Commit 9baf6cb388924538147dabe13180b06cc46c0251 has been approved by GuillaumeGomez

workingjubilee · 2022-01-18T07:06:06Z

Somehow, this got set to p=1.
It will likely get rolled up later, and it would be inconvenient if it skipped ahead of rollup=never PRs without being rolled up.

@bors p=0

bors · 2022-01-18T10:07:35Z

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

This switches to just use size, weight, and spacing to distinguish headings in the sidebar. We no longer use boxes, horizontal bars, or centering to distinguish headings. This makes it much easier to understand the hierarchy of headings, and reduces visual noise. I also refactored how the mobile topbar works. Previously, we tried to shift around elements from the sidebar to make the topbar. Now, the topbar gets its own elements, which can be styled on their own. This makes styling and reasoning about those elements simpler. Because the heading font sizes are bigger, increase the sidebar width slightly. As a very minor change, removed version from the "All types" page. It's now only on the crate page.

jsha · 2022-01-18T19:41:30Z

@bors r=GuillaumeGomez rollup

bors · 2022-01-18T19:41:31Z

📌 Commit 6a5f8b1 has been approved by GuillaumeGomez

…askrgr Rollup of 9 pull requests Successful merges: - rust-lang#90782 (Implement raw-dylib support for windows-gnu) - rust-lang#91150 (Let qpath contain NtTy: `<$:ty as $:ty>::…`) - rust-lang#92425 (Improve SIMD casts) - rust-lang#92692 (Simplify and unify rustdoc sidebar styles) - rust-lang#92780 (Directly use ConstValue for single literals in blocks) - rust-lang#92924 (Delete pretty printer tracing) - rust-lang#93018 (Remove some unused `Ord` derives based on `Span`) - rust-lang#93026 (fix typo in `max` description for f32/f64) - rust-lang#93035 (Fix stdarch submodule pointing to commit outside tree) Failed merges: - rust-lang#92861 (Rustdoc mobile: put out-of-band info on its own line) r? `@ghost` `@rustbot` modify labels: rollup

…laumeGomez rustdoc mobile: fix scroll offset when jumping to internal id Followup to rust-lang#92692. The semantics of `scroll-margin-top` are a little surprising - the attribute needs to be applied to the element that gets scrolled into the viewport, not the scrolling element. This fixes an issue where clicking on a method (or other item) from the sidebar takes you to a scroll position where the topbar covers up the method name. I'm interested in ideas for how to test this with browser-ui-test, but I think it doesn't yet have what I need. What I need is an assert that `<element>.getBoundingClientRect().y` is > 45. Demo: https://rustdoc.crud.net/jsha/fix-scroll-padding-top/std/string/struct.String.html#method.extend_from_within r? `@GuillaumeGomez`

nbdd0121 · 2022-01-24T11:39:11Z

I have to say that I really dislike the new style, especially in dark mode. It is much less accessible than previous style.

The biggest issue is contrast.

In the dark theme, the foreground color is #D2991D and the background color of the sidebar is #505050. The computed contrast ratio (using https://webaim.org/resources/contrastchecker/) is 3.19:1 and this violates WCAG AA's requirement of >4.5:1 for normal-sized text.
The section division is less clear than the previous style. Color and font size becomes the only way to distinguish.
The link color in dark mode really stands out, and having a whole sidebar full of the color made the situation worse.
The added padding to the sidebar and warping reduces the information density of the sidebar.
Not sure if this is introduced by this PR, but [src] is changed to source. This makes the page feel visually more crowded. Since this is there for all items instead of a link it should be treated as a button (like the run button of code snippets).

Overall for documentation I think accessibility, clarity and easiness to navigate is much more important than style discrepencies.

GuillaumeGomez · 2022-01-24T16:03:14Z

There is #93231 open to reduce this issue. Does it improve your situation?

nbdd0121 · 2022-01-24T16:54:34Z

It certainly helps with the contrast issue. But I still think the old UI style is much more usable and pragmatic.

I suggest that an user survey to be performed for such a major UI change.

camelid · 2022-01-25T01:51:47Z

Our goal with this change was to make the sidebar easier to use and less cluttered, but I agree that some changes may have made it worse. I do think that decreasing padding and finding a way to increase distinctions between different components of the sidebar would be good.

The [src] -> source change was made in a different PR: #92602

jsha · 2022-01-25T03:40:12Z

FYI, the vertical spacing is precisely the same before and after:

The left margin went from to 10px to 24px. However, the max width of the sidebar went from 200px to 250px. As a result, more of the method names are visible than before.

There is indeed a bug with wrapping / ellipsis, which I think was introduced in a different change. I'll send a patch for that shortly.

nbdd0121 · 2022-01-25T03:48:20Z

I use a vertically oriented display for doc viewing, so the added left margin means less horizontal space for the content. Perhaps the left margin should be adaptive to the screen width?

RDambrosio016 · 2022-03-12T20:58:59Z

I personally think that changing the color to be yellow is fine (though i prefer white). However i really dislike the removal of the separator lines, i.e. the border around the struct name and the lines around Methods and similar. Without it it just looks all merged and without clear separation, i just think it looks worse overall.

pravic · 2022-04-08T18:05:42Z

However i really dislike the removal of the separator lines, i.e. the border around the struct name and the lines around Methods and similar. Without it it just looks all merged and without clear separation, i just think it looks worse overall.

I confirm. The new UI looks as a regression, it's just plain flat. Not that the old UI was perfect, but it was consistent across Rust versions with gradual QOL improvements.

I've created #95816 as a regression report and then was pointed out to this PR.

jsha added T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. A-rustdoc-ui Area: rustdoc UI (generated HTML) labels Jan 9, 2022

rust-highfive assigned GuillaumeGomez Jan 9, 2022

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jan 9, 2022

This comment has been minimized.

Sign in to view

GuillaumeGomez reviewed Jan 9, 2022

View reviewed changes

src/librustdoc/html/render/mod.rs Outdated Show resolved Hide resolved

GuillaumeGomez reviewed Jan 9, 2022

View reviewed changes

src/librustdoc/html/render/mod.rs Outdated Show resolved Hide resolved

This comment has been minimized.

Sign in to view

jsha force-pushed the cool-sidebar branch from dd75db9 to 29bc50f Compare January 10, 2022 01:13

This comment has been minimized.

Sign in to view

jsha force-pushed the cool-sidebar branch from 908dadb to e68e148 Compare January 13, 2022 16:36

GuillaumeGomez reviewed Jan 14, 2022

View reviewed changes

src/librustdoc/html/static/js/main.js Show resolved Hide resolved

GuillaumeGomez reviewed Jan 14, 2022

View reviewed changes

src/test/rustdoc/cap-lints.rs Show resolved Hide resolved

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Jan 18, 2022

bors added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels Jan 18, 2022

jsha force-pushed the cool-sidebar branch from 9baf6cb to 6a5f8b1 Compare January 18, 2022 18:45

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Jan 18, 2022

matthiaskrgr mentioned this pull request Jan 18, 2022

Rollup of 9 pull requests #93048

Merged

bors merged commit ff476b3 into rust-lang:master Jan 19, 2022

rustbot added this to the 1.60.0 milestone Jan 19, 2022

jsha deleted the cool-sidebar branch January 19, 2022 03:00

jsha mentioned this pull request Jan 19, 2022

rustdoc mobile: fix scroll offset when jumping to internal id #93067

Merged

GuillaumeGomez mentioned this pull request Jan 22, 2022

Fixes footer with new sidebar changes rust-lang/docs.rs#1619

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Simplify and unify rustdoc sidebar styles #92692

Simplify and unify rustdoc sidebar styles #92692

jsha commented Jan 9, 2022 •

edited

Loading

rust-highfive commented Jan 9, 2022

This comment has been minimized.

GuillaumeGomez commented Jan 9, 2022

GuillaumeGomez commented Jan 9, 2022

GuillaumeGomez commented Jan 9, 2022 •

edited

Loading

GuillaumeGomez commented Jan 9, 2022

GuillaumeGomez commented Jan 9, 2022

jsha commented Jan 9, 2022

jsha commented Jan 9, 2022

This comment has been minimized.

camelid commented Jan 9, 2022

jsha commented Jan 10, 2022

This comment has been minimized.

camelid commented Jan 10, 2022 •

edited

Loading

This comment has been minimized.

This comment has been minimized.

GuillaumeGomez commented Jan 12, 2022

bors commented Jan 13, 2022

jsha commented Jan 13, 2022

GuillaumeGomez commented Jan 14, 2022

jsha commented Jan 18, 2022

bors commented Jan 18, 2022

workingjubilee commented Jan 18, 2022

bors commented Jan 18, 2022

jsha commented Jan 18, 2022

bors commented Jan 18, 2022

nbdd0121 commented Jan 24, 2022 •

edited

Loading

GuillaumeGomez commented Jan 24, 2022

nbdd0121 commented Jan 24, 2022

camelid commented Jan 25, 2022 •

edited

Loading

jsha commented Jan 25, 2022

nbdd0121 commented Jan 25, 2022

RDambrosio016 commented Mar 12, 2022

pravic commented Apr 8, 2022

Simplify and unify rustdoc sidebar styles #92692

Simplify and unify rustdoc sidebar styles #92692

Conversation

jsha commented Jan 9, 2022 • edited Loading

rust-highfive commented Jan 9, 2022

This comment has been minimized.

GuillaumeGomez commented Jan 9, 2022

GuillaumeGomez commented Jan 9, 2022

GuillaumeGomez commented Jan 9, 2022 • edited Loading

GuillaumeGomez commented Jan 9, 2022

GuillaumeGomez commented Jan 9, 2022

jsha commented Jan 9, 2022

jsha commented Jan 9, 2022

This comment has been minimized.

camelid commented Jan 9, 2022

jsha commented Jan 10, 2022

This comment has been minimized.

camelid commented Jan 10, 2022 • edited Loading

This comment has been minimized.

This comment has been minimized.

GuillaumeGomez commented Jan 12, 2022

bors commented Jan 13, 2022

jsha commented Jan 13, 2022

GuillaumeGomez commented Jan 14, 2022

jsha commented Jan 18, 2022

bors commented Jan 18, 2022

workingjubilee commented Jan 18, 2022

bors commented Jan 18, 2022

jsha commented Jan 18, 2022

bors commented Jan 18, 2022

nbdd0121 commented Jan 24, 2022 • edited Loading

GuillaumeGomez commented Jan 24, 2022

nbdd0121 commented Jan 24, 2022

camelid commented Jan 25, 2022 • edited Loading

jsha commented Jan 25, 2022

nbdd0121 commented Jan 25, 2022

RDambrosio016 commented Mar 12, 2022

pravic commented Apr 8, 2022

jsha commented Jan 9, 2022 •

edited

Loading

GuillaumeGomez commented Jan 9, 2022 •

edited

Loading

camelid commented Jan 10, 2022 •

edited

Loading

nbdd0121 commented Jan 24, 2022 •

edited

Loading

camelid commented Jan 25, 2022 •

edited

Loading