| Age | Commit message (Collapse) | Author | Lines |
|---|
|
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?
|
|
There's no such thing as a big section header, so I don't know why the
name was used.
|
|
|
|
rustdoc: stop preloading Source Serif 4 Bold
According to #91170, italic fonts are not preloaded because they're rarely used, but bold fonts are. This seems to be true of bold Source Code Pro and bold Fira Sans, but bold and italic Source Serif Pro seem to be equally heavily used.
This is, I assume, the result of using Fira Sans Bold and Source Code Bold headings, so you only get bold Serif text when the doc author uses strong `**` emphasis (or within certain kinds of tooltip, which shouldn't be preloaded because they only show up long after the page is loaded).
To check this, run these two commands in the browser console to measure how much they're used. The measurement is extremely rough, but it gets the idea across: the two styles are about equally popular.
// count bold elements
Array.prototype.slice.call(document.querySelectorAll("*")).filter(x => { const y = document.defaultView.getComputedStyle(x); return y.fontFamily.indexOf("Source Serif 4") !== -1 && y.fontWeight > 400 }).length
// count italic elements
Array.prototype.slice.call(document.querySelectorAll("*")).filter(x => { const y = document.defaultView.getComputedStyle(x); return y.fontFamily.indexOf("Source Serif 4") !== -1 && y.fontStyle == "italic" }).length
| URL | Bold | Italic |
|--------------|-----:|-------:|
| [std] | 2 | 9 |
| [Vec] | 8 | 89 |
| [regex] | 33 | 17 |
| [test_suite] | 0 | 0 |
[std]: https://doc.rust-lang.org/nightly/std/index.html
[Vec]: https://doc.rust-lang.org/nightly/std/vec/struct.Vec.html
[regex]: https://docs.rs/regex/1.9.5/regex/index.html
[test_suite]: https://docs.rs/test-suite/3.2.9/test_suite/
|
|
This line is longer than 100 characters, but apparently,
[tidy's list of checked extensions] doesn't include html,
so the line length doesn't matter.
[tidy's list of checked extensions]: https://github.com/rust-lang/rust/blob/31be8cc41148983e742fea8f559aacca0f6647db/src/tools/tidy/src/style.rs#L245
|
|
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
|
|
This removes an HTTP request from the loading pipeline,
and allows it to be changed with a media query.
|
|
|
|
This commit makes three changes for consistency and readability:
- It shows the sibling navigation on module pages. It's weird
that it didn't work before, and is inconsistent with everything
else (even Crates have sibling navigation with other Crates).
- It hides the "In [parent]" header if it's the same as the
current crate, and if there's no other header between them.
We need to keep it on modules and types, since they have
their own header and data between them, and we don't want
to show siblings under a header implying that they're children.
- It adds a margin to deal with the headers butting directly into
the branding lockup.
|
|
|
|
This should result in a layout for the actual standard library,
when built on CI, that looks like this:
_____
/ \ std
| R | 1.74.0-nightly
\_____/
(203c57dbe 2023-09-17)
Having the whole version as one string caused it to flex wrap,
because the sidebar isn't wide enough to fit the whole thing.
|
|
This commit changes the layout to something a bit less "look at my logo!!!111"
gigantic, and makes it clearer where clicking the logo will actually take you.
It also means the crate name is persistently at the top of the sidebar, even
when in a sub-item page, and clicking that name takes you back to the root.
| | 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/fe2ce102-d4b8-44e6-9f7b-68636a907f56
[short-subpage]: https://github.com/rust-lang/rust/assets/1593513/29501663-56c0-4151-b7de-d2637e167125
[long-root]: https://github.com/rust-lang/rust/assets/1593513/f6a385c0-b4c5-4a9c-954b-21b38de4192f
[long-subpage]: https://github.com/rust-lang/rust/assets/1593513/97ec47b4-61bf-4ebe-b461-0d2187b8c6ca
https://notriddle.com/rustdoc-html-demo-4/logo-lockup/image/index.html
https://notriddle.com/rustdoc-html-demo-4/logo-lockup/crossbeam_channel/index.html
https://notriddle.com/rustdoc-html-demo-4/logo-lockup/adler/struct.Adler32.html
https://notriddle.com/rustdoc-html-demo-4/logo-lockup/crossbeam_channel/struct.Sender.html
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
In newer versions of rustdoc, the crate name and version are always shown in
the sidebar, even in subpages. Clicking the crate name does the same thing
clicking the logo always did: return you to the crate root.
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.
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.
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
Has anyone written the rationale on why the Rust logo shows up on projects that
aren't the standard library? If we turned it off on non-standard crates by
default, it would line wrap crate names a lot less often.
Or maybe we should encourage crate authors to include their own logo more
often? It certainly helps give people a better sense of "place."
I'm not sure of anything that directly follows up this one. Plenty of other
changes could be made to improve the layout, like
* coming up with a less cluttered way to do disclosure (there's a lot of `[-]`
on the page)
* doing a better job of separating lateral navigation (vec::Vec links to
vec::IntoIter) and the table of contents (vec::Vec links to vec::Vec::new)
* giving readers more control of how much rustdoc hows them, and giving doc
authors more control of how much it generates
* better search that reduces the need to browse
But those are mostly orthogonal, not future possibilities unlocked by this change.
|
|
|
|
|
|
According to 4198fac7390509128c42757fcfb89a0effde4a8e, italic fonts are
not preloaded because they're rarely used, but bold fonts are. This
seems to be true of bold Source Code Pro and bold Fira Sans, but
bold and italic Source Serif Pro seem to be equally heavily used.
This is, I assume, the result of using Fira Sans Bold and Source Code
Bold headings, so you only get bold Serif text when the doc author
uses strong `**` emphasis (or within certain kinds of tooltip,
which shouldn't be preloaded because they only show up long after
the page is loaded).
To check this, run these two commands in the browser console to
measure how much they're used. The measurement is extremely rough,
but it gets the idea across: the two styles are about equally popular.
// count bold elements
Array.prototype.slice.call(document.querySelectorAll("*")).filter(x => { const y = document.defaultView.getComputedStyle(x); return y.fontFamily.indexOf("Source Serif 4") !== -1 && y.fontWeight > 400 }).length
// count italic elements
Array.prototype.slice.call(document.querySelectorAll("*")).filter(x => { const y = document.defaultView.getComputedStyle(x); return y.fontFamily.indexOf("Source Serif 4") !== -1 && y.fontStyle == "italic" }).length
| URL | Bold | Italic |
|---------|-----:|-------:|
| [std] | 2 | 9 |
| [Vec] | 8 | 89 |
| [regex] | 33 | 17 |
[std]: https://doc.rust-lang.org/nightly/std/index.html
[Vec]: https://doc.rust-lang.org/nightly/std/vec/struct.Vec.html
[regex]: https://docs.rs/regex/1.9.5/regex/index.html
|
|
Based on
https://github.com/rust-lang/rust/pull/115812#issuecomment-1717960119
Having them in separate files used to make more sense, before the
migration to CSS variables made the theme files as small as they are
nowadays. This is already how docs.rs and mdBook do it.
|
|
|
|
This was added in 003b2bc1c65251ec2fc80b78ed91c43fb35402ec and used to build
the URL of the theme stylesheets. It isn't used any more, because
f9e1f6ffdf03ec33cb29e20c88fc7bcc938c7f42 changed it so that the URL was
supplied in a `<meta>` tag, which also provides the hashes of the files.
|
|
we are migrating to askama
see https://github.com/rust-lang/rust/issues/108868
|
|
|
|
Since the directory that contains source files is called `src`,
it makes sense to name the scripts that way, too.
|
|
The CSS uses an inconsistent mix of both. This commit switches
it to always use `src`.
|
|
Co-authored-by: Dániel Buga <bugadani@gmail.com>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
rustdoc: migrate `document_type_layout` to askama
|
|
|
|
|
|
|
|
`static.files` folder
|
|
|
|
rustdoc: migrate item_union to an Askama template
|
|
|
|
|
|
Render source page layout with Askama
~~I was looking at making `code_html` render into the buffer instead of in advance, but it turned out to need a pretty big refactor, so starting with rearranging the high-level layout.~~
Found another approach which required much less changes
cc #108868
|
|
|
|
|
|
|
|
Co-authored-by: Michael Howell <michael@notriddle.com>
|
|
rustdoc: Migrate sidebar rendering to Askama
cc #108757
Renders the sidebar for documentation using an Askama template
|
|
rustdoc: Migrate `document_item_info` to Askama
https://rust-lang.zulipchat.com/#narrow/stream/266220-rustdoc/topic/rustdoc.20allocations.20are.20slow
Hoping to piece-by-piece migrate things to template. Had a few failed attempts at more complex parts of the code, so this is just a start.
|
|
|
|
|
|
To avoid generating a FOUC at startup, this commit uses `document.write` to
load the stylesheet initially.
Co-Authored-By: Guillaume Gomez <guillaume1.gomez@gmail.com>
|
