https://github.com/rust-lang/rust http://git.dreamy.place/mirrors/rust/atom?h=1.76.0 2023-12-15T10:51:23+00:00 2023-12-15T10:51:23+00:00 Guillaume Gomez guillaume1.gomez@gmail.com 2023-12-15T10:51:23+00:00 urn:sha1:f8b92697a1c444eea01ae9e723c40a35e42ad42c rustdoc: allow resizing the sidebar / hiding the top bar Fixes #97306 Preview: http://notriddle.com/rustdoc-html-demo-4/sidebar-resize/std/index.html  ## 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. https://github.com/rust-lang/rust/issues/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). https://github.com/rust-lang/rust/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? 2023-11-27T07:21:19+00:00 Matthias Krüger matthias.krueger@famsik.de 2023-11-27T07:21:19+00:00 urn:sha1:828db2860f275d3e0ce07f746fca6ffce089da68 Fix Rustdoc search docs link This link has been outdated since #112725 moved the search docs to their own page 2023-11-26T16:22:43+00:00 clubby789 jamie@hill-daniel.co.uk 2023-11-26T16:22:43+00:00 urn:sha1:4d9344d26ebe8ac6ede26ca054a57334be4299ad 2023-11-25T19:33:04+00:00 Michael Howell michael@notriddle.com 2023-11-25T19:20:03+00:00 urn:sha1:bdcf91605caf75969919ae366e5e0561dcd85ea5 According to [MDN], this function is compatible with: * Chrome 16 and Edge 12 * Firefox 9 * Safari 1.1 and iOS Safari 1 These browsers are well within our [support matrix], which requires compatibility with Chrome 118, Firefox 115, Safari 17, and Edge 119. [MDN]: https://developer.mozilla.org/en-US/docs/Web/API/Node/contains#browser_compatibility [support matrix]: https://browsersl.ist/#q=last+2+Chrome+versions%2C+last+1+Firefox+version%2C+Firefox+ESR%2C+last+1+Safari+version%2C+last+1+iOS+version%2C+last+1+Edge+version%2C+last+1+UCAndroid+version 2023-11-13T06:21:21+00:00 Michael Howell michael@notriddle.com 2023-11-13T06:21:21+00:00 urn:sha1:8b1bcc8d5ba65ecf6741436246ed27f74a71d40c This didn't show up in our local tests, because the problem is actually caused by docs.rs rewritten HTML (which relocates the classes that this code looked for from the body tag to a child div). Fixes #117290 2023-10-22T23:51:32+00:00 Michael Howell michael@notriddle.com 2023-10-07T06:31:16+00:00 urn:sha1:46fdeb24fd16156f73d95272b48604ab967c81db 2023-10-22T22:56:15+00:00 Michael Howell michael@notriddle.com 2023-10-06T19:06:52+00:00 urn:sha1:62c67a6438aac23f7c757322be880ca45f2b6b63 2023-10-22T22:56:14+00:00 Michael Howell michael@notriddle.com 2023-10-06T01:44:52+00:00 urn:sha1:fa10e4d667aea7ca869eb53f9af925a5fa120c84 This is an attempt to balance three problems, each of which would be violated by a simpler implementation: - A type alias should show all the `impl` blocks for the target type, and vice versa, if they're applicable. If nothing was done, and rustdoc continues to match them up in HIR, this would not work. - Copying the target type's docs into its aliases' HTML pages directly causes far too much redundant HTML text to be generated when a crate has large numbers of methods and large numbers of type aliases. - Using JavaScript exclusively for type alias impl docs would be a functional regression, and could make some docs very hard to find for non-JS readers. - Making sure that only applicable docs are show in the resulting page requires a type checkers. Do not reimplement the type checker in JavaScript. So, to make it work, rustdoc stashes these type-alias-inlined docs in a JSONP "database-lite". The file is generated in `write_shared.rs`, included in a `<script>` tag added in `print_item.rs`, and `main.js` takes care of patching the additional docs into the DOM. The format of `trait.impl` and `type.impl` JS files are superficially similar. Each line, except the JSONP wrapper itself, belongs to a crate, and they are otherwise separate (rustdoc should be idempotent). The "meat" of the file is HTML strings, so the frontend code is very simple. Links are relative to the doc root, though, so the frontend needs to fix that up, and inlined docs can reuse these files. However, there are a few differences, caused by the sophisticated features that type aliases have. Consider this crate graph: ```text --------------------------------- | crate A: struct Foo<T> | | type Bar = Foo<i32> | | impl X for Foo<i8> | | impl Y for Foo<i32> | --------------------------------- | ---------------------------------- | crate B: type Baz = A::Foo<i8> | | type Xyy = A::Foo<i8> | | impl Z for Xyy | ---------------------------------- ``` The type.impl/A/struct.Foo.js JS file has a structure kinda like this: ```js JSONP({ "A": [["impl Y for Foo<i32>", "Y", "A::Bar"]], "B": [["impl X for Foo<i8>", "X", "B::Baz", "B::Xyy"], ["impl Z for Xyy", "Z", "B::Baz"]], }); ``` When the type.impl file is loaded, only the current crate's docs are actually used. The main reason to bundle them together is that there's enough duplication in them for DEFLATE to remove the redundancy. The contents of a crate are a list of impl blocks, themselves represented as lists. The first item in the sublist is the HTML block, the second item is the name of the trait (which goes in the sidebar), and all others are the names of type aliases that successfully match. This way: - There's no need to generate these files for types that have no aliases in the current crate. If a dependent crate makes a type alias, it'll take care of generating its own docs. - There's no need to reimplement parts of the type checker in JavaScript. The Rust backend does the checking, and includes its results in the file. - Docs defined directly on the type alias are dropped directly in the HTML by `render_assoc_items`, and are accessible without JavaScript. The JSONP file will not list impl items that are known to be part of the main HTML file already. [JSONP]: https://en.wikipedia.org/wiki/JSONP 2023-10-11T19:15:33+00:00 Michael Howell michael@notriddle.com 2023-10-11T19:15:33+00:00 urn:sha1:fd9f1a7148b47722d617bd896a8ead7211762d22 2023-10-11T17:28:54+00:00 Michael Howell michael@notriddle.com 2023-10-07T18:10:36+00:00 urn:sha1:77fa09d9a1ddc7f99b0cda10c26688fe6f2b5519 This makes two changes, based on experimenting with different browsers: - It debounces resizing the body text. This improves behavior on huge pages like struct.Vec.html, because it doesn't have to do layout. - It does the sidebar width updates directly on the sidebar instead of doing it on the `<HTML>` element. Doing it on `<HTML>` causes it to recalculate CSS for the entire document, also causing layout jank.