Skip to content
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 and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make the Rustdoc Sidebar hideable, even on larger viewports #97306

Closed
VincentWo opened this issue May 23, 2022 · 5 comments · Fixed by #115660
Closed

Make the Rustdoc Sidebar hideable, even on larger viewports #97306

VincentWo opened this issue May 23, 2022 · 5 comments · Fixed by #115660
Labels
A-rustdoc-ui Area: Rustdoc UI (generated HTML) C-feature-request Category: A feature request, i.e: not implemented / a PR. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@VincentWo
Copy link

I often open the RustDoc Documentation of a crate on the left and my own code on the right. Since I don't have the biggest screen this means that a lot of the code is hard to read and requires scrolling:
A screenshot of a RustDoc Page, showing that the size of the sidebar on the left forces the code on the right to have horizontal scroll
I propose to show a button, similar as on the smaller viewports, that allows hiding the sidebar, which would turn this into:
A screenshot showing the rustdoc page without the sidebar, not forcing the code to horizontal scroll
This makes the code and the docs in general much more readable and reduces visual clutter on smaller screens.

I think that it would be an improvement to also allow the hiding of the sidebar on bigger screens, though I also could understand the argument to hide the control on even bigger screens.

I am aware of #59829 and hope that the additional control that is proposed here does not add even more visual clutter, I am not an expert in this topic, I can just say that as a Person with ADHD (not dyslexia) the hidden sidebar makes the documentation much easier to digest, but I can't speak for other people. Maybe @lambda could be so kind to comment on this.

I can also create a Mockup, I just wanted to check first whether this is even an idea worth discussing.

@GuillaumeGomez GuillaumeGomez added T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. C-feature-request Category: A feature request, i.e: not implemented / a PR. A-rustdoc-ui Area: Rustdoc UI (generated HTML) labels May 23, 2022
@GuillaumeGomez
Copy link
Member

I don't think allowing to hide the sidebar is a good idea for the general documentation as it contains important information.

What we could do is change the minimum width required to switch to "mobile mode" where the sidebar is hidden by default (because mobile devices have very few space to spare).

cc @jsha

@VincentWo
Copy link
Author

If this is the less controversial approach than I am all for it :)

@GuillaumeGomez
Copy link
Member

By curiosity: what's your viewport width?

@VincentWo
Copy link
Author

Oh yes, sorry for not including it.
Using a 14' Macbook Air M1 with Firefox, so probably not the most unusual setup:
Full-Screen: 1440px
Using it on only the half: 714px

@crispinb
Copy link

I don't think allowing to hide the sidebar is a good idea for the general documentation as it contains important information.

I've also found the sidebar horizontal dominance a bit of a problem, for the same reason as the OP. I don't think hiding the sidebar will cause a problem as long as it's visible on first load & is easy/discoverable to retrieve (and it doesn't cause problems for similar doc browsers eg. Elixir's). A fixed width cutoff would mean that those of us using some form of window tiling would have to adjust our window manager to fit Rust docs, which seems the wrong way round (to this Rust newbie).

@bors bors closed this as completed in f8b9269 Dec 15, 2023
rust-timer added a commit to rust-lang-ci/rust that referenced this issue Dec 15, 2023
Rollup merge of rust-lang#115660 - notriddle:notriddle/sidebar-resize, r=GuillaumeGomez

rustdoc: allow resizing the sidebar / hiding the top bar

Fixes rust-lang#97306

Preview: http://notriddle.com/rustdoc-html-demo-4/sidebar-resize/std/index.html

![image](https://github.com/rust-lang/rust/assets/1593513/a2f40ea2-0436-4e44-99e8-d160dab2a680)

## Summary

This feature adds:

1. A checkbox to the Settings popover to hide the persistent navigation bar (the sidebar on large viewports and the top bar on small ones).
2. On large viewports, it adds a resize handle to the persistent sidebar. Resizing it into nothing is equivalent to turning off the persistent navigation bar checkbox in Settings.
3. If the navigation bar is hidden, a toolbar button to the left of the search appears. Clicking it brings the navigation bar back.

## Motivation

While "mobile mode" is definitely a good default, it's not the only reason people have wanted to hide the sidebar:

* Some people use tiling window managers, and don't like rustdoc's current breakpoints. Changing the breakpoints might help with that, but there's no perfect solution, because there's a gap between "huge screen" and "smartphone" where reasonable people can disagree about whether it makes sense for the sidebar to be on-screen. rust-lang#97306

* Some people ask for ways to reduce on-screen clutter because it makes it easier to focus. There's not a media query for that (and if there was, privacy-conscious users would turn it off). rust-lang#59829

This feature is designed to avoid these problems. Resizing the sidebar especially helps, because it provides a way to hide the sidebar without adding a new top-level button (which would add clutter), and it provides a way to make rustdoc play nicer in complex, custom screen layouts.

## Guide and Reference-level explanation

On a desktop or laptop with a mouse, resize the sidebar by dragging its right edge.

On any browser, including mobile phones, the sticky top bar or side bar can be hidden from the Settings area (the button with the cog wheel, next to the search bar). When it's hidden, a convenient button will appear on the search bar's left.

## Drawbacks

This adds more JavaScript code to the render blocking area.

## Rationale and alternatives

The most obvious way to allow people to hide the sidebar would have been to let them "manually enter mobile mode." The upside is that it's a feature we already have. The downside is that it's actually really hard to come up with a terse description. Is it:

* A Setting that forces desktop viewers to always have the mobile-style top bar? If so, how do we label it? Should it be visible on mobile, and, if so, does it just not do anything?
* A persistent hide/show sidebar button, present on desktop, just like on mobile? That's clutter that I'd like to avoid.

## Prior art

* The new file browser in GitHub uses a similar divider with a mouse-over indicator
* mdBook and macOS Finder both allow you to resize the sidebar to nothing as a gesture to hide it
* https://www.nngroup.com/articles/drag-drop/

## Future possibilities

https://rust-lang.zulipchat.com/#narrow/stream/266220-rustdoc/topic/Table.20of.20contents proposes a new, second sidebar (a table of contents). How should it fit in with this feature? Should it be resizeable? Hideable? Can it be accessed on mobile?
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-rustdoc-ui Area: Rustdoc UI (generated HTML) C-feature-request Category: A feature request, i.e: not implemented / a PR. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants