rustdoc: allow resizing the sidebar / hiding the top bar #115660

notriddle · 2023-09-08T04:29:50Z

Fixes #97306

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

Summary

This feature adds:

A checkbox to the Settings popover to hide the persistent navigation bar (the sidebar on large viewports and the top bar on small ones).
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.
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. Make the Rustdoc Sidebar hideable, even on larger viewports #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). Rustdoc formatting presents accessibility issues #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?

rustbot · 2023-09-08T04:29:58Z

r? @jsha

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

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

GuillaumeGomez · 2023-09-08T08:58:10Z

I'm not sure if it's intended but when you reduce the sidebar width too much, it just disappears (width of the layout: 860px) and then you can make it appear again.

Otherwise, I think it's a good idea overall. Just very curious what others will think about it.

cc @rust-lang/rustdoc

Nemo157 · 2023-09-08T10:00:06Z

With js disabled the cursor still changes to appear like it's resizable, maybe the cursor css should be injected from js to avoid that.

I also wonder if there should be a small element showing that this region is interact-able, something like

notriddle · 2023-09-08T17:28:49Z

@GuillaumeGomez

It was intended to get rid of the sidebar, and there's a toggle option in the settings popover to bring it back. I wanted to see if you could find it. Since you didn't, I've added an easier way.

Screencast.from.2023-09-08.09-08-26.webm

@Nemo157

Good catch on disabling javascript. I've added a rule to noscript.css to fix that.

I'm not sure that the visible handle is a good idea. mdBook doesn't have one, Sublime Text and VSCodium don't have one, macOS Finder doesn't have one, and even the Firefox sidebar (which does have an explicit border) doesn't bother with the grabby track any more to indicate resizeability.

This indicates that other designers don't think it's a problem. It also means users likely won't understand what the icon means even if it's there, because they might never have seen it before.

GuillaumeGomez · 2023-09-08T17:57:11Z

We removed buttons on the left of the search bar and I'm not sure it's a good idea to put back one there. I think only having the setting in the settings menu should be enough (and not be able to make disappear when resizing).

Nemo157 · 2023-09-08T18:10:18Z

mdBook doesn't have one

Well, this is the first I hear that the mdBook sidebar is resizeable, I've never even considered that it might be. Maybe this is just from growing up with native UIs, but I expect that native app panes would be resizeable, while web pages generally aren't so I won't try.

GuillaumeGomez · 2023-09-08T18:15:00Z

mdBook doesn't have one

Well, this is the first I hear that the mdBook sidebar is resizeable, I've never even considered that it might be. Maybe this is just from growing up with native UIs, but I expect that native app panes would be resizeable, while web pages generally aren't so I won't try.

Forgot to mention but I didn't know mdBook could be resized. The proposition of @Nemo157 to add a little symbol just right the sidebar to make it visible that it's resizeable is a good idea I think.

notriddle · 2023-09-08T19:21:23Z

We removed buttons on the left of the search bar and I'm not sure it's a good idea to put back one there. I think only having the setting in the settings menu should be enough (and not be able to make disappear when resizing).

I supported the move to drop the paintbrush icon because it didn't make sense for the single most prominent button in the entire application to be the theme switcher. This button brings up global navigation, so it makes sense to give it pride of placement.

Well, this is the first I hear that the mdBook sidebar is resizeable, I've never even considered that it might be. Maybe this is just from growing up with native UIs, but I expect that native app panes would be resizeable, while web pages generally aren't so I won't try.

This is a very good usability report. rust-lang/mdBook#2186

jsha · 2023-09-08T21:26:24Z

Ooh I like this design a lot, particularly the flow that goes settings menu -> hide persistent navigation bar -> button appears to show the sidebar again. I agree with @notriddle's logic about putting the button to the left of the sidebar. I'll add a couple of things:

it doesn't show up for most users (those who haven't changed the setting)
for those users who do change the setting, it's highly relevant and useful, so it's worth some screen real estate
putting it to the left of the search bar makes sense because that's close to where the sidebar normally is, so that's where someone might look to expose the sidebar.

The interaction for resizing the sidebar is indeed very hard to discover, perhaps because the interactable zone (where the cursor changes to indicate <->) is very small. I also didn't know mdbook had a resizeable sidebar! I don't love the idea of a permanently-visible drag handle, though.

What do you think of landing the hide/show interaction first while we brainstorm other approaches to the fine-grained resizing problem? Or we could land the resizing code with the current design even though it's not very discoverable.

GuillaumeGomez · 2023-09-09T11:37:29Z

To help with discoverability, we could make the handle appear when we hover the sidebar?

putting it to the left of the search bar makes sense because that's close to where the sidebar normally is, so that's where someone might look to expose the sidebar.

The big problem with that (and that's happened to me) is that if you scrolled down, the search bar isn't visible anymore and you don't see the button appear. Then I had no idea that it could be changed in the settings. I think as long as this part isn't fixed, we shouldn't hide the sidebar completely when resizing it.

rustdoc: show crate name beside smaller logo *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 <details><summary>Before</summary> | | Macro | Module | |--|-------|--------| | In crate | ![image](https://github.com/rust-lang/rust/assets/1593513/d5db0a46-2bb6-44a2-a3aa-2d915ecb8595) |![image](https://github.com/rust-lang/rust/assets/1593513/61f8c1ee-c298-4e2c-b791-18ecb79ab83b) | In module[^1] | ![image](https://github.com/rust-lang/rust/assets/1593513/73abca59-0b69-4650-a1e2-7278ca34795c) | ![image](https://github.com/rust-lang/rust/assets/1593513/0baf02c2-2ec7-4674-80e5-a6a74a973376) [^1]: This PR also includes a bug fix for derive macros not showing up in the lateral navigation part of the sidebar </details> #### Whole sidebar screenshots | | Macro | Module | |--|-------|--------| | In crate | ![image](https://github.com/rust-lang/rust/assets/1593513/75d1bd07-41f7-4f11-ba24-fd5476e0586a) | ![image](https://github.com/rust-lang/rust/assets/1593513/52960259-2b65-4131-b380-01826f0a0eb7) | In module | ![image](https://github.com/rust-lang/rust/assets/1593513/06e57928-8cb0-41bd-b152-be16cc53e5ec) | ![image](https://github.com/rust-lang/rust/assets/1593513/37291c69-2a07-4467-a382-d9b029084a47) #### Different logo configurations | | Short crate name | Long crate name | |---------|------------------|-----------------| | Root | ![short-root] | ![long-root] | Subpage | ![short-subpage] | ![long-subpage] [short-root]: https://github.com/rust-lang/rust/assets/1593513/9e2b4fa8-f581-4106-b562-1e0372c13f79 [short-subpage]: https://github.com/rust-lang/rust/assets/1593513/8331cdb8-fa13-4671-a1e2-dcc1cdca7451 [long-root]: https://github.com/rust-lang/rust/assets/1593513/7d377fec-0f1d-4343-9f82-0e35a8f58056 [long-subpage]: https://github.com/rust-lang/rust/assets/1593513/3b3094a4-63c9-477c-8c15-b6075837df30 ##### Without a logo ![image](https://github.com/rust-lang/rust/assets/1593513/66672b79-6c59-4be8-a527-25ef6f0b04ab) ### 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). [Phoenix's Hexdocs]: https://hexdocs.pm/phoenix/1.7.7/overview.html [Internals Discourse]: https://internals.rust-lang.org/t/poc-of-a-new-design-for-the-generated-rustdoc/11018 ## 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. [`opentelemetry_process_propagator`]: https://hexdocs.pm/opentelemetry_process_propagator/OpentelemetryProcessPropagator.html ## 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](https://utherii.github.io/new.html) 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? ![image](https://github.com/rust-lang/rust/assets/1593513/e969faf7-7722-457a-b8c6-8d962e9e1e23) * Give readers more control of how much rustdoc shows them, and giving doc authors more control of how much it generates. Basically, rust-lang/rust#115660 is great, let's do it too. But those are mostly orthogonal, not future possibilities unlocked by this change.

rfcbot · 2023-12-04T20:52:07Z

🔔 This is now entering its final comment period, as per the review above. 🔔

notriddle · 2023-12-07T19:11:24Z

Just realized but the PR includes in its title "hiding the top bar". I didn't see where it was done though. Did I miss something obvious?

For posterity's sake (I know we mentioned this in a meeting) the mobile-mode top bar can be hidden by clicking into the settings popover and unchecking "Show persistent navigation bar."

rfcbot · 2023-12-14T20:55:00Z

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.

GuillaumeGomez · 2023-12-15T10:28:04Z

@bors r+

bors · 2023-12-15T10:28:06Z

📌 Commit fd9f1a7 has been approved by GuillaumeGomez

It is now in the queue for this repository.

…llaumeGomez Rollup of 4 pull requests Successful merges: - rust-lang#113091 (Don't merge cfg and doc(cfg) attributes for re-exports) - rust-lang#115660 (rustdoc: allow resizing the sidebar / hiding the top bar) - rust-lang#118863 (rustc_mir_build: Enforce `rustc::potential_query_instability` lint) - rust-lang#118909 (Some cleanup and improvement for invalid ref casting impl) r? `@ghost` `@rustbot` modify labels: rollup

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?

…iddle rustdoc ui: adjust tooltip z-index to be above sidebar In rust-lang#115660 the sidebar's z-index was changed to 100. This PR changes the tooltip's z-index to 101 to be above the sidebar again. Fixes [after beta-backport] rust-lang#119472.

Rollup merge of rust-lang#119477 - lukas-code:tooltip-z-index, r=notriddle rustdoc ui: adjust tooltip z-index to be above sidebar In rust-lang#115660 the sidebar's z-index was changed to 100. This PR changes the tooltip's z-index to 101 to be above the sidebar again. Fixes [after beta-backport] rust-lang#119472.

Pkgsrc changes: * Adapt checksums and patches. Upstream chnages: Version 1.76.0 (2024-02-08) ========================== Language -------- - [Document Rust ABI compatibility between various types] (rust-lang/rust#115476) - [Also: guarantee that char and u32 are ABI-compatible] (rust-lang/rust#118032) - [Warn against ambiguous wide pointer comparisons] (rust-lang/rust#117758) Compiler -------- - [Lint pinned `#[must_use]` pointers (in particular, `Box<T>` where `T` is `#[must_use]`) in `unused_must_use`.] (rust-lang/rust#118054) - [Soundness fix: fix computing the offset of an unsized field in a packed struct] (rust-lang/rust#118540) - [Soundness fix: fix dynamic size/align computation logic for packed types with dyn Trait tail] (rust-lang/rust#118538) - [Add `$message_type` field to distinguish json diagnostic outputs] (rust-lang/rust#115691) - [Enable Rust to use the EHCont security feature of Windows] (rust-lang/rust#118013) - [Add tier 3 {x86_64,i686}-win7-windows-msvc targets] (rust-lang/rust#118150) - [Add tier 3 aarch64-apple-watchos target] (rust-lang/rust#119074) - [Add tier 3 arm64e-apple-ios & arm64e-apple-darwin targets] (rust-lang/rust#115526) Refer to Rust's [platform support page][platform-support-doc] for more information on Rust's tiered platform support. Libraries --------- - [Add a column number to `dbg!()`] (rust-lang/rust#114962) - [Add `std::hash::{DefaultHasher, RandomState}` exports] (rust-lang/rust#115694) - [Fix rounding issue with exponents in fmt] (rust-lang/rust#116301) - [Add T: ?Sized to `RwLockReadGuard` and `RwLockWriteGuard`'s Debug impls.] (rust-lang/rust#117138) - [Windows: Allow `File::create` to work on hidden files] (rust-lang/rust#116438) Stabilized APIs --------------- - [`Arc::unwrap_or_clone`] (https://doc.rust-lang.org/stable/std/sync/struct.Arc.html#method.unwrap_or_clone) - [`Rc::unwrap_or_clone`] (https://doc.rust-lang.org/stable/std/rc/struct.Rc.html#method.unwrap_or_clone) - [`Result::inspect`] (https://doc.rust-lang.org/stable/std/result/enum.Result.html#method.inspect) - [`Result::inspect_err`] (https://doc.rust-lang.org/stable/std/result/enum.Result.html#method.inspect_err) - [`Option::inspect`] (https://doc.rust-lang.org/stable/std/option/enum.Option.html#method.inspect) - [`type_name_of_val`] (https://doc.rust-lang.org/stable/std/any/fn.type_name_of_val.html) - [`std::hash::{DefaultHasher, RandomState}`] (https://doc.rust-lang.org/stable/std/hash/index.html#structs) These were previously available only through `std::collections::hash_map`. - [`ptr::{from_ref, from_mut}`] (https://doc.rust-lang.org/stable/std/ptr/fn.from_ref.html) - [`ptr::addr_eq`](https://doc.rust-lang.org/stable/std/ptr/fn.addr_eq.html) Cargo ----- See [Cargo release notes] (https://github.com/rust-lang/cargo/blob/master/CHANGELOG.md#cargo-176-2024-02-08). Rustdoc ------- - [Don't merge cfg and doc(cfg) attributes for re-exports] (rust-lang/rust#113091) - [rustdoc: allow resizing the sidebar / hiding the top bar] (rust-lang/rust#115660) - [rustdoc-search: add support for traits and associated types] (rust-lang/rust#116085) - [rustdoc: Add highlighting for comments in items declaration] (rust-lang/rust#117869) Compatibility Notes ------------------- - [Add allow-by-default lint for unit bindings] (rust-lang/rust#112380) This is expected to be upgraded to a warning by default in a future Rust release. Some macros emit bindings with type `()` with user-provided spans, which means that this lint will warn for user code. - [Remove x86_64-sun-solaris target.] (rust-lang/rust#118091) - [Remove asmjs-unknown-emscripten target] (rust-lang/rust#117338) - [Report errors in jobserver inherited through environment variables] (rust-lang/rust#113730) This [may warn](rust-lang/rust#120515) on benign problems too. - [Update the minimum external LLVM to 16.] (rust-lang/rust#117947) - [Improve `print_tts`](rust-lang/rust#114571) This change can break some naive manual parsing of token trees in proc macro code which expect a particular structure after `.to_string()`, rather than just arbitrary Rust code. - [Make `IMPLIED_BOUNDS_ENTAILMENT` into a hard error from a lint] (rust-lang/rust#117984) - [Vec's allocation behavior was changed when collecting some iterators] (rust-lang/rust#110353) Allocation behavior is currently not specified, nevertheless changes can be surprising. See [`impl FromIterator for Vec`] (https://doc.rust-lang.org/nightly/std/vec/struct.Vec.html#impl-FromIterator%3CT%3E-for-Vec%3CT%3E) for more details. - [Properly reject `default` on free const items] (rust-lang/rust#117818)

rustdoc: show crate name beside smaller logo *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 <details><summary>Before</summary> | | Macro | Module | |--|-------|--------| | In crate | ![image](https://github.com/rust-lang/rust/assets/1593513/d5db0a46-2bb6-44a2-a3aa-2d915ecb8595) |![image](https://github.com/rust-lang/rust/assets/1593513/61f8c1ee-c298-4e2c-b791-18ecb79ab83b) | In module[^1] | ![image](https://github.com/rust-lang/rust/assets/1593513/73abca59-0b69-4650-a1e2-7278ca34795c) | ![image](https://github.com/rust-lang/rust/assets/1593513/0baf02c2-2ec7-4674-80e5-a6a74a973376) [^1]: This PR also includes a bug fix for derive macros not showing up in the lateral navigation part of the sidebar </details> #### Whole sidebar screenshots | | Macro | Module | |--|-------|--------| | In crate | ![image](https://github.com/rust-lang/rust/assets/1593513/75d1bd07-41f7-4f11-ba24-fd5476e0586a) | ![image](https://github.com/rust-lang/rust/assets/1593513/52960259-2b65-4131-b380-01826f0a0eb7) | In module | ![image](https://github.com/rust-lang/rust/assets/1593513/06e57928-8cb0-41bd-b152-be16cc53e5ec) | ![image](https://github.com/rust-lang/rust/assets/1593513/37291c69-2a07-4467-a382-d9b029084a47) #### Different logo configurations | | Short crate name | Long crate name | |---------|------------------|-----------------| | Root | ![short-root] | ![long-root] | Subpage | ![short-subpage] | ![long-subpage] [short-root]: https://github.com/rust-lang/rust/assets/1593513/9e2b4fa8-f581-4106-b562-1e0372c13f79 [short-subpage]: https://github.com/rust-lang/rust/assets/1593513/8331cdb8-fa13-4671-a1e2-dcc1cdca7451 [long-root]: https://github.com/rust-lang/rust/assets/1593513/7d377fec-0f1d-4343-9f82-0e35a8f58056 [long-subpage]: https://github.com/rust-lang/rust/assets/1593513/3b3094a4-63c9-477c-8c15-b6075837df30 ##### Without a logo ![image](https://github.com/rust-lang/rust/assets/1593513/66672b79-6c59-4be8-a527-25ef6f0b04ab) ### 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). [Phoenix's Hexdocs]: https://hexdocs.pm/phoenix/1.7.7/overview.html [Internals Discourse]: https://internals.rust-lang.org/t/poc-of-a-new-design-for-the-generated-rustdoc/11018 ## 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. [`opentelemetry_process_propagator`]: https://hexdocs.pm/opentelemetry_process_propagator/OpentelemetryProcessPropagator.html ## 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](https://utherii.github.io/new.html) 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? ![image](https://github.com/rust-lang/rust/assets/1593513/e969faf7-7722-457a-b8c6-8d962e9e1e23) * Give readers more control of how much rustdoc shows them, and giving doc authors more control of how much it generates. Basically, rust-lang/rust#115660 is great, let's do it too. But those are mostly orthogonal, not future possibilities unlocked by this change.

notriddle requested a review from GuillaumeGomez September 8, 2023 04:29

rustbot assigned jsha Sep 8, 2023

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Sep 8, 2023

notriddle force-pushed the notriddle/sidebar-resize branch from 96836e7 to cc5a9ca Compare September 8, 2023 04:43

This comment has been minimized.

Sign in to view

GuillaumeGomez reviewed Sep 8, 2023

View reviewed changes

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

This comment has been minimized.

Sign in to view

notriddle mentioned this pull request Sep 8, 2023

"I didn't know that the sidebar could be resized" rust-lang/mdBook#2186

Closed

notriddle force-pushed the notriddle/sidebar-resize branch from 59deae0 to 4463bb3 Compare September 8, 2023 21:16

notriddle force-pushed the notriddle/sidebar-resize branch from 8a0326a to 800dab0 Compare September 11, 2023 20:34

This comment has been minimized.

Sign in to view

notriddle force-pushed the notriddle/sidebar-resize branch from 800dab0 to dc3db00 Compare September 11, 2023 21:06

This comment has been minimized.

Sign in to view

notriddle force-pushed the notriddle/sidebar-resize branch 3 times, most recently from 8714dd1 to 01756e2 Compare September 11, 2023 22:07

notriddle marked this pull request as ready for review September 11, 2023 22:08

notriddle force-pushed the notriddle/sidebar-resize branch 2 times, most recently from 0d5d6d0 to 86c10e8 Compare October 11, 2023 17:32

rustdoc: fix resize trouble with mobile

fd9f1a7

rfcbot added final-comment-period In the final comment period and will be merged soon unless new substantive objections are raised. and removed proposed-final-comment-period Proposed to merge/close by relevant subteam, see T-<team> label. Will enter FCP once signed off. labels Dec 4, 2023

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-review Status: Awaiting review from the assignee but also interested parties. labels Dec 15, 2023

GuillaumeGomez mentioned this pull request Dec 15, 2023

Rollup of 4 pull requests #118975

Merged

bors merged commit f8b9269 into rust-lang:master Dec 15, 2023
11 checks passed

rustbot added this to the 1.76.0 milestone Dec 15, 2023

notriddle deleted the notriddle/sidebar-resize branch December 15, 2023 14:58

apiraino removed the to-announce Announce this issue on triage meeting label Dec 28, 2023

lukas-code mentioned this pull request Dec 31, 2023

rustdoc ui: adjust tooltip z-index to be above sidebar #119477

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

rustdoc: allow resizing the sidebar / hiding the top bar #115660

rustdoc: allow resizing the sidebar / hiding the top bar #115660

notriddle commented Sep 8, 2023 •

edited

Loading

rustbot commented Sep 8, 2023

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

GuillaumeGomez commented Sep 8, 2023

Nemo157 commented Sep 8, 2023

notriddle commented Sep 8, 2023

This comment has been minimized.

GuillaumeGomez commented Sep 8, 2023

Nemo157 commented Sep 8, 2023

GuillaumeGomez commented Sep 8, 2023

notriddle commented Sep 8, 2023

jsha commented Sep 8, 2023

GuillaumeGomez commented Sep 9, 2023

This comment has been minimized.

This comment has been minimized.

rfcbot commented Dec 4, 2023

notriddle commented Dec 7, 2023

rfcbot commented Dec 14, 2023

GuillaumeGomez commented Dec 15, 2023

bors commented Dec 15, 2023

rustdoc: allow resizing the sidebar / hiding the top bar #115660

rustdoc: allow resizing the sidebar / hiding the top bar #115660

Conversation

notriddle commented Sep 8, 2023 • edited Loading

Summary

Motivation

Guide and Reference-level explanation

Drawbacks

Rationale and alternatives

Prior art

Future possibilities

rustbot commented Sep 8, 2023

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

GuillaumeGomez commented Sep 8, 2023

Nemo157 commented Sep 8, 2023

notriddle commented Sep 8, 2023

This comment has been minimized.

GuillaumeGomez commented Sep 8, 2023

Nemo157 commented Sep 8, 2023

GuillaumeGomez commented Sep 8, 2023

notriddle commented Sep 8, 2023

jsha commented Sep 8, 2023

GuillaumeGomez commented Sep 9, 2023

This comment has been minimized.

This comment has been minimized.

rfcbot commented Dec 4, 2023

notriddle commented Dec 7, 2023

rfcbot commented Dec 14, 2023

GuillaumeGomez commented Dec 15, 2023

bors commented Dec 15, 2023

notriddle commented Sep 8, 2023 •

edited

Loading