Make impl section headers sticky by GuillaumeGomez · Pull Request #133717 · rust-lang/rust (original) (raw)
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
[ Show hidden characters]({{ revealButtonHref }})
Fixes #133506.
It makes impl sections headings sticky, allowing users to know what impl items they are currently going through.
You can test it here.
Some technical details: to make it work (because summary use both ::before and ::after pseudo-elements), I needed to give some left margin and padding so that the other collapse/expand toggles of children items would not appear on the sticky heading's toggle. Hence why the GUI tests new values look so weird.
r? @notriddle
Status: Awaiting review from the assignee but also interested parties.
Relevant to the rustdoc team, which will review and decide on the PR/issue.
labels
This comment has been minimized.
Forgot to push the second commit updating GUI tests...
It's messed up when the sidebar is hidden. Otherwise, seems fine.
Kinda fixed the mess up with the sidebar button. Not perfect but sadly, we can't set an element position based on the page scroll without JS, and with JS, having a listener on the page scroll is terrible for performance. So instead, I simply make the button above the heading. It'll prevent to collapse the heading if the button is present, but I think it's ok.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This issue / PR is in PFCP or FCP with a disposition to merge it.
and removed T-rustdoc
Relevant to the rustdoc team, which will review and decide on the PR/issue.
labels
The trouble with this sort of thing is that it's really hard to get all the interaction features right. Here's a few cases that act weird:
- If I click an item in the sidebar, it gets lost underneath the impl header.
Normally, the solution to this one isscroll-margin-top, as in rustdoc mobile: fix scroll offset when jumping to internal id #93067, but, unfortunately, we don't know how tall the impl header is:
- If I collapse an impl block while I'm scrolled some distance into it, I wind up at some arbitrary point in the document. I don't know how to fix this one without JS.
- Hidden navigation bar is still a mess on mobile:
@rfcbot concern scroll-margin-top
@rfcbot concern scroll after collapse
@rfcbot concern mobile hidden persistent navigation bar
(In favor of this general design, but echo notriddle's concern that this is really tricky to get right, so we should spend some time experimenting and ensuring it works in all scenarios)
I'm interested in seeing this happen to make impls more comprehensible, but I would like to recommend that this sticky header should be optional. I know that optional UI features are a cost in themselves, but I have two specific reasons that unconditional stickiness could be problematic:
- If the sticky header is tall enough, relative to the viewport (yes, I do use rustdoc on my phone) then there may not be enough remaining space to comfortably read the documentation text.
- And how much space that is will depend not just on the viewport size but also the content and style of the documentation itself — how tall the function signatures, body text, code examples, etc. are, and how much context is needed from one part to understand another. So, a size threshold would not completely solve the problem.
- Some people find sticky headers and other content-overlapping fixed elements inherently distressing to view (I have a little bit of this myself) — it's something about losing the consistency that the entire content scrolls as a single unit within a well-defined boundary, combined with the shrinking of the effective usable viewport. Being able to avoid sticky headers should be considered an accessibility feature.