Emit more valid HTML from rustdoc
Previously, tidy-html5 (`tidy`) would complain about a few things in our HTML. The main thing is that `<summary>` tags can't contain `<div>`s. That's easily fixed by changing out the `<div>`s for `<span>`s with `display: block`.
However, there's also a rule that `<span>`s can't contain heading elements. `<span>` permits only "phrasing content" https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span, and `<h3>` (and friends) are "Flow content, heading content, palpable content". https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements
We have a wrapping `<div>` that goes around each `<h3>`/`<h4>`, etc. We turn that into a `<section>` rather than a `<span>` because `<section>` permits "flow content". https://developer.mozilla.org/en-US/docs/Web/HTML/Element/section
After this change we get only three warnings from tidy, run on struct.String.html:
line 6 column 10790 - Warning: trimming empty <span>
line 1 column 1118 - Warning: <link> proprietary attribute "disabled"
line 1 column 1193 - Warning: <link> proprietary attribute "disabled"
The empty `<span>` is a known issue - there's a span in front of the search box to work around a strange Safari issue.
The `<link>` attributes are the non-default stylesheets. We can probably refactor theme application to avoid using this proprietary "disabled" attribute.
We can suppress those warnings with flags to tidy, and get a run that returns 0 (success):
```
tidy -o /dev/null -quiet --drop-empty-elements no --warn-proprietary-attributes no build/x86_64-unknown-linux-gnu/doc/std/string/trait.ToString.html
```
Note: this requires the latest version of tidy-html5, built from https://github.com/htacg/tidy-html5. Older versions (including the default version on Ubuntu 21.10) think `<section>` can't occur inside `<summary>`.
Demo: https://rustdoc.crud.net/jsha/fix-rustdoc-html/std/string/struct.String.html
r? `@GuillaumeGomez`
Previously, tidy-html5 (`tidy`) would complain about a few things in our
HTML. The main thing is that `<summary>` tags can't contain `<div>`s.
That's easily fixed by changing out the `<div>`s for `<span>`s with
`display: block`.
However, there's also a rule that `<span>`s can't contain heading
elements. `<span>` permits only "phrasing content"
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span, and
`<h3>` (and friends) are "Flow content, heading content, palpable
content".
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements
We have a wrapping `<div>` that goes around each `<h3>`/`<h4>`,
etc. We turn that into a `<section>` rather than a `<span>` because
`<section>` permits "flow content".
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/section
After this change we get only three warnings from tidy, run on
struct.String.html:
line 6 column 10790 - Warning: trimming empty <span>
line 1 column 1118 - Warning: <link> proprietary attribute "disabled"
line 1 column 1193 - Warning: <link> proprietary attribute "disabled"
The empty `<span>` is a known issue - there's a span in front of the
search box to work around a strange Safari issue.
The `<link>` attributes are the non-default stylesheets. We can probably
refactor theme application to avoid using this proprietary "disabled"
attribute.
Previously, the radio button choices for themes would wrap awkwardly on
narrow screens. With this change, the group of choices will prefer
bumping down to the next line together, leaving the setting name on its
own line.
Also fix some minor spacing issues:
- Align the setting name vertically with the radio button choices.
- Use margin instead of padding for most spacing choices.
- Use no margin/padding on the right-hand side.
This reduces the number of clicks required to change theme.
Also, simplify the UI a bit (remove setting grouping), and add a "Back"
link close to the settings icon.
rustdoc: decouple stability and const-stability
This PR tweaks the stability rendering code to consider stability and const-stability separately. This fixes two issues:
- Stabilities that match the enclosing item are now always omitted, even if the item has const-stability as well (#90552)
- Const-stable unstable functions will now have their (const-) stability rendered.
Fixes#90552.
This switches to just use size, weight, and spacing to distinguish
headings in the sidebar. We no longer use boxes, horizontal bars, or
centering to distinguish headings. This makes it much easier to
understand the hierarchy of headings, and reduces visual noise.
I also refactored how the mobile topbar works. Previously, we tried to
shift around elements from the sidebar to make the topbar. Now, the
topbar gets its own elements, which can be styled on their own. This
makes styling and reasoning about those elements simpler.
Because the heading font sizes are bigger, increase the sidebar width
slightly.
As a very minor change, removed version from the "All types" page. It's
now only on the crate page.
Pick themes on settings page, not every page
This hides the paintbrush icon on most pages by default, in preference for the settings on the settings page. When loading from a local file, and not in mobile view, continue to show the theme picker. That's because some browsers limit access to localStorage from file:/// URLs, so choosing a theme from settings.html doesn't take effect.
Fixes#84539
Part of #59840
r? `@GuillaumeGomez`
Demo: https://rustdoc.crud.net/jsha/theme-picker-local-only-2/std/io/trait.Read.html
Migrate rustdoc from Tera to Askama
See #84419.
Should probably get a benchmarking run to verify if it has the intended effect on rustdoc performance.
cc `@jsha` `@jyn514.`
Remove `SymbolStr`
This was originally proposed in https://github.com/rust-lang/rust/pull/74554#discussion_r466203544. As well as removing the icky `SymbolStr` type, it allows the removal of a lot of `&` and `*` occurrences.
Best reviewed one commit at a time.
r? `@oli-obk`
`render/context` always runs after `run_global_context`, so it was always set to `true`.
This is a holdover from when rustdoc allowed configuring passes, but the `collapse-docs` pass was
removed ages ago, and the ability to configure passes is about to be removed.
By changing `as_str()` to take `&self` instead of `self`, we can just
return `&str`. We're still lying about lifetimes, but it's a smaller lie
than before, where `SymbolStr` contained a (fake) `&'static str`!
rustdoc: Consolidate static-file replacement mechanism
There were a few places in rustdoc where we would take static JS or CSS and rewrite it at doc generation time to insert values. This consolidates all the CSS instances into one CSS file and replaces the JS examples with data- attributes on the rustdoc-vars div.
Demo https://rustdoc.crud.net/jsha/static-file-replace/test_docs/
r? ``@GuillaumeGomez``
I would like to rename it to `Type::Path`, but then it can't be
re-exported since the name would conflict with the `Path` struct.
Usually enum variants are referred to using their qualified names in
Rust (and parts of rustdoc already do that with `clean::Type`), so this
is also more consistent with the language.
rustdoc: Remove `ResolvedPath.did`
`ResolvedPath.did` was not actually the same as `.path.def_id()`. Instead,
`.did` referred to the `DefId` of the page to be used as a hyperlink target.
For example, a link to `Struct::method()` would use `Struct`'s `DefId` as its
`.did` field. This behavior is confusing, easy to accidentally misuse, and can
instead be obtained on-demand when computing hyperlink targets. It's also likely
part of the reason `kind_side_channel` exists. I'm currently working on some
experimental refactorings in `collect_intra_doc_links` that I believe require --
or at least benefit from -- removing `.did`.
r? `@jyn514`
We carry around a list of stylesheets that can carry two different types
of thing:
1. Internal stylesheets specific to a page type (only for settings)
2. Themes
In this change I move the link generation for settings.css into
settings(), so Context.style_files is reserved just for themes.
We had two places where we extracted a base theme name from a list of
StylePaths. I consolidated that code to be a method on StylePath.
I moved generation of link tags for stylesheets into the page.html
template. With that change, I made the template responsible for special
handling of light.css (making it the default theme) and of the other
themes (marking them disabled). That allowed getting rid of the
`disabled` field on StylePath.
