check item.is_fake() instead of self_id.is_some()
Remove empty branching in Attributes::from_ast
diverse small refacto after Josha review
cfg computation moved in merge_attrs
refacto use from_ast twice for coherence
take cfg out of Attributes and move it to Item
Use details tag for trait implementors.
Part of #83332 and following on from #83337 and #83355.
This removes one category of JS-generated toggles (implementors), and replaces them with a `<details>` tag. This simplifies the JS, and fixes some bugs where things that were supposed to be hidden by the toggle were not hidden. Compare https://hoffman-andrews.com/rust/details-implementors/std/io/trait.Read.html#impl-Read vs https://doc.rust-lang.org/nightly/std/io/trait.Read.html#implementors.
This introduces a `left: -23px` to put the toggle in the correct place, matching the current style for `.collapse-toggle`.
It's worth noting this introduces a slight behavior change: since the entire line is now a `<summary>`, any part of the line is clickable. So for instance, in `impl Read for File`, clicking `impl` or `for` will collapse / expand the docs. Clicking `Read` or `File` still links to the appropriate documentation as before.
* Remove `prefix` param of `document_short/full`, `render_markdown`, as its always an empty string.
* Remove `Option` wrapping of `document_short` `parent`, as its always `Some`.
rustdoc: Reduce visual weight of attributes.
Followup from #83337. As part of that PR, we stopped hiding attributes behind a toggle, because most things have just zero or one attributes. However, this made clear that the current rendering of attributes emphasizes them a lot, which distracts from function signatures. This PR changes their color of attributes to be the same as the toggles, and reduces their font weight.
This also removes `#[lang]` from the list of ALLOWED_ATTRIBUTES. This attribute is an implementation detail rather than part of the public-facing documentation.
Demo at https://hoffman-andrews.com/rust/de-emph-attr/std/string/struct.String.html#method.trim
Instead of using a depth counter and adding "../" to get to the top,
this commit makes rustdoc actually compare the path of what it's
linking from to the path that it's linking to. This makes the resulting
HTML shorter.
Here's a comparison of one of the largest (non-source) files in the
Rust standard library docs (about 4% improvement before gzipping).
$ wc -c struct.Wrapping.old.html struct.Wrapping.new.html
2387389 struct.Wrapping.old.html
2298538 struct.Wrapping.new.html
Most if it can be efficiently gzipped away.
$ wc -c struct.Wrapping.old.html.gz struct.Wrapping.new.html.gz
70679 struct.Wrapping.old.html.gz
70050 struct.Wrapping.new.html.gz
But it also makes a difference in the final DOM size, reducing it from 91MiB to 82MiB.
rustdoc: Hide item contents, not items
This tweaks rustdoc to hide item contents instead of items, and only when there are too many of them.
This means that users will _always_ see the type parameters, and will _often_ see fields/etc as long as they are small. Traits have some heuristics for hiding only the methods or only the methods and the consts, since the associated types are super important.
I'm happy to play around with the heuristics here; we could potentially make it so that structs/enums/etc are always hidden but traits will try really hard to show type aliases.
This needs a test, but you can see it rendered at https://manishearth.net/sand/doc_render/bar/
<details>
<summary> Code example </summary>
```rust
pub struct PubStruct {
pub a: usize,
pub b: usize,
}
pub struct BigPubStruct {
pub a: usize,
pub b: usize,
pub c: usize,
pub d: usize,
pub e: usize,
pub f: usize,
}
pub union BigUnion {
pub a: usize,
pub b: usize,
pub c: usize,
pub d: usize,
pub e: usize,
pub f: usize,
}
pub union Union {
pub a: usize,
pub b: usize,
pub c: usize,
}
pub struct PrivStruct {
a: usize,
b: usize,
}
pub enum Enum {
A, B, C,
D {
a: u8,
b: u8
}
}
pub enum LargeEnum {
A, B, C, D, E, F, G, H, I, J
}
pub trait Trait {
type A;
#[must_use]
fn foo();
fn bar();
}
pub trait GinormousTrait {
type A;
type B;
type C;
type D;
type E;
type F;
const N: usize = 1;
#[must_use]
fn foo();
fn bar();
}
pub trait HugeTrait {
type A;
const M: usize = 1;
const N: usize = 1;
const O: usize = 1;
const P: usize = 1;
const Q: usize = 1;
#[must_use]
fn foo();
fn bar();
}
pub trait BigTrait {
type A;
#[must_use]
fn foo();
fn bar();
fn baz();
fn quux();
fn frob();
fn greeble();
}
#[macro_export]
macro_rules! foo {
(a) => {a};
}
```
</details>
Fixes https://github.com/rust-lang/rust/issues/82114
Introduce a first use of the `<details>` and `<summary>` tags as
replacements for the JS-built toggles. I think this has the potential to
replace all the JS toggles and generally clean up the JS, CSS, and HTML.
Split rendering of attributes into two cases: in the case where they are
rendered as descendents of a `<pre>` tag, where they use indent spaces and
newlines for formatting, matching their surrounding markup. In the case
where they are rendered as descendants of a `<code>` tag, they are
rendered as `<div>`. This let me clean up some fragile CSS that was
adjusting the margin-left of attributes depending on context.
Remove toggles for attributes. With the ALLOWED_ATTRIBUTES filter, it's
rare for an item to have more than one attribute, so hiding attributes
behind a toggle doesn't save any screen space in the common case.
Fix a couple of invocations of `matches!` that didn't compile on my
machine.
Fix a boolean for the JS `createToggle` call that was causing
"Expand description" to show up spuriously on already-expanded
descriptions.
Add JS for auto-hide settings and hide all / show all.
Remove a z-index property and some font color tweaks made unnecessary
by the <details> toggles.
Add CSS for the <details> toggles.
Move `SharedContext` to `context.rs`
It is tightly connected to `Context` and is primarily used as a field in
`Context`. Thus, it should be next to `Context`.
rustdoc: sort search index items for compression
This should not affect the appearance of the docs pages themselves.
This makes the pre-compressed search index smaller, thanks to the
empty-string path duplication format, and also the gzipped version,
by giving the algorithm more structure to work with.
rust$ wc -c search-index-old.js search-index-new.js
2628334 search-index-old.js
2586181 search-index-new.js
5214515 total
rust$ gzip search-index-*
rust$ wc -c search-index-old.js.gz search-index-new.js.gz
239486 search-index-old.js.gz
237386 search-index-new.js.gz
476872 total
List trait impls before deref methods in doc's sidebar
This PR is acting directly on a suggestion made by ```````@jyn514``````` in #83133. I've tested the changes locally, and can confirm that it does in fact properly achieve what he thought it would. This PR also in turn closes#83133.
Remove unneeded INITIAL_IDS const
Some IDs inside this map didn't exist anymore, some others were duplicates of what we have inside `IdMap`. So instead of keeping the two around and since `INITIAL_IDS` was only used by `IdMap`, no need to keep both of them.
This should not affect the appearance of the docs pages themselves.
This makes the pre-compressed search index smaller, thanks to the
empty-string path duplication format, and also the gzipped version,
by giving the algorithm more structure to work with.
rust$ wc -c search-index-old.js search-index-new.js
2628334 search-index-old.js
2586181 search-index-new.js
5214515 total
rust$ gzip search-index-*
rust$ wc -c search-index-old.js.gz search-index-new.js.gz
239486 search-index-old.js.gz
237386 search-index-new.js.gz
476872 total
Avoid temporary allocations in `render_assoc_item`
`render_assoc_item` came up as very hot in a profile of rustdoc on
`bevy`. This avoids some temporary allocations just to calculate the
length of the header.
This should be a strict improvement, since all string formatting was
done twice before.
cc #82845
This essentially switches search-index.js from a "array of struct"
to a "struct of array" format, like this:
{
"doc": "Crate documentation",
"t": [ 1, 1, 2, 3, ... ],
"n": [ "Something", "SomethingElse", "whatever", "do_stuff", ... ],
"q": [ "a::b", "", "", "", ... ],
"d": [ "A Struct That Does Something", "Another Struct", "a function", "another function", ... ],
"i": [ 0, 0, 1, 1, ... ],
"f": [ null, null, [], [], ... ],
"p": ...,
"a": ...
}
So `{ty: 1, name: "Something", path: "a::b", desc: "A Struct That Does Something", parent_idx: 0, search_type: null}` is the first item.
This makes the uncompressed version smaller, but it really shows on the
compressed version:
notriddle:rust$ wc -c new-search-index1.52.0.js
2622427 new-search-index1.52.0.js
notriddle:rust$ wc -c old-search-index1.52.0.js
2725046 old-search-index1.52.0.js
notriddle:rust$ gzip new-search-index1.52.0.js
notriddle:rust$ gzip old-search-index1.52.0.js
notriddle:rust$ wc -c new-search-index1.52.0.js.gz
239385 new-search-index1.52.0.js.gz
notriddle:rust$ wc -c old-search-index1.52.0.js.gz
296328 old-search-index1.52.0.js.gz
notriddle:rust$
That's a 4% improvement on the uncompressed version (fewer `[]`),
and 20% improvement after gzipping it, thanks to putting like-typed
data next to each other. Any compression algorithm based on a sliding
window will probably show this kind of improvement.
rustdoc: Cleanup `html::render::Context`
- Move most shared fields to `SharedContext` (except for `cache`, which
isn't mutated anyway)
- Replace a use of `Arc` with `Rc`
- Make a bunch of fields private
- Add static size assertion for `Context`
- Don't share `id_map` and `deref_id_map`
`render_assoc_item` came up as very hot in a profile of rustdoc on
`bevy`. This avoids some temporary allocations just to calculate the
length of the header.
This should be a strict improvement, since all string formatting was
done twice before.
All the tests passed, so it doesn't seem they need to be shared.
Plus they should be item/page-specific.
I'm not sure why they were shared before. I think the reason `id_map`
worked as a shared value before is that it is cleared before rendering
each item (in `render_item`). And then I'm guessing `deref_id_map`
worked because it's a hashmap keyed by `DefId`, so there was no overlap
(though I'm guessing we could have had issues in the future).
Note that `id_map` currently still has to be cleared because otherwise
child items would inherit the `id_map` of their parent. I'm hoping to
figure out a way to stop cloning `Context`, but until then we have to
reset `id_map`.
Instead of being loaded on every page, the JS search index is now
loaded when either (a) there is a `?search=` param, or (b) the search
input is focused.
This saves both CPU and bandwidth. As of Feb 2021,
https://doc.rust-lang.org/search-index1.50.0.js is 273,838 bytes
gzipped or 2,544,939 bytes uncompressed. Evaluating it takes 445 ms
of CPU time in Chrome 88 on a i7-10710U CPU (out of a total ~2,100
ms page reload).
Generate separate JS file with crate names.
This is much smaller than the full search index, and is used in the "hot
path" to draw the page. In particular it's used to crate the dropdown
for the search bar, and to append a list of crates to the sidebar (on
some pages).
Skip early search that can bypass 500ms timeout.
This was occurring when someone had typed some text during the load of
search-index.js. Their query was usually not ready to execute, and the
search itself is fairly expensive, delaying the overall load, which
delayed the input / keyup events, which delayed eventually executing the
query.
The same information is available everywhere; the only reason the dummy
cache was needed is because it waas previously stored in three different
places. This consolidates the info a bit so the cache in `DocContext` is
used throughout. As a bonus, it means `renderinfo` is used much much
less.
- Return a `Cache` from `run_global_ctxt`, not `RenderInfo`
- Remove the unused `render_info` from `run_renderer`
- Remove RefCell around `inlined`
- Add intra-doc links
rustdoc: add optional woff2 versions of FiraSans.
For browsers that support woff2 (most modern ones:
https://caniuse.com/woff2), this offers a reduction in download size
for these two fonts from 362k to 257k (32% reduction). It decreases the
total page size for `struct.String.html` (counting all subresources) by
about 2.5%.
If this is interesting, I'm happy to apply the same treatment to the
other fonts, but these two are the biggest.
- Take `FnMut` in `rustc_trait_selection::find_auto_trait_generics`
- Take `&mut DocContext` in most of `clean`
- Collect the iterator in auto_trait_impls instead of iterating lazily; the lifetimes were really bad.
- Changes `fn sess` to properly return a borrow with the lifetime of `'tcx`, not the mutable borrow.
The `Deref` cycle checks added as part of #80653 were "unbalanced" in the sense
that the main content code path checks for cycles _before_ descending, while the
sidebar checks _after_. Checking _before_ is correct, so this changes the
sidebar path to match the main content path.
* Reuse memory
* simplify `next_def_id`, avoid multiple hashing and unnecessary lookups
* remove `all_fake_def_ids`, use the global map instead (probably not a good step toward parallelization, though...)
* convert `add_deref_target` to iterative implementation
* use `ArrayVec` where we know the max number of elements
* minor touchups here and there
* avoid building temporary vectors that get appended to other vectors
At most places I may or may not be doing the compiler's job is this PR.
Fix rendering of stabilization version for trait implementors
Rustdoc compares an item's stabilization version with its parent's to not render it if they are the same. Here, the implementor was compared with itself, resulting in the stabilization version never getting shown.
This probably needs a test.
Fixes#80777.
r? `@jyn514`
Fix <unknown> queries and add more timing info to render_html
Closes https://github.com/rust-lang/rust/issues/81251.
## Fix `<unknown>` queries
This happened because `alloc_query_strings` was never called.
## Add more timing info to render_html
This still has some issues I'm not sure how to work out:
- `create_renderer` and `renderer_after_krate` aren't shown by default.
I want something like `verbose_generic_activity_with_arg`, but it doesn't exist.
I'm also not sure how to show activities that aren't on by default - I
tried `-Z self-profile -Z self-profile-args=all`, but it didn't show up.
r? `@wesleywiser`
Remove doctree::StructType
Also removes it from the Union type, as unions can only ever be 'Plain'. Adds a new StructType to JSON, 'union', as the easiest way to encode the type of a union there. This leaves only one item in doctree, `Module`.
r? `@jyn514`
[rustdoc] Box ItemKind to reduce the size of `Item`
This brings the size of `Item` from
```
[src/librustdoc/lib.rs:103] std::mem::size_of::<Item>() = 536
```
to
```
[src/librustdoc/lib.rs:103] std::mem::size_of::<Item>() = 136
```
This is an alternative to https://github.com/rust-lang/rust/pull/79967; I don't think it makes sense to make both changes.
Helps with #79103.
This is a squash of these commits:
- Highlight edition-specific keywords correctly in code blocks,
accounting for code block edition modifiers
- Fix unit tests
- Revert changes to rustc_span::symbol to prepare for merge of #80272
- Use new Symbol::is_reserved API from #80272
- Remove unused import added by accident when merging
This brings the size of `Item` from
```
[src/librustdoc/lib.rs:103] std::mem::size_of::<Item>() = 680
```
to
```
[src/librustdoc/lib.rs:103] std::mem::size_of::<Item>() = 280
```
Remove `DefPath` from `Visibility` and calculate it on demand
Depends on #80090 and should not be merged before. Helps with https://github.com/rust-lang/rust/issues/79103 and https://github.com/rust-lang/rust/issues/76382.
cc https://github.com/rust-lang/rust/pull/80014#issuecomment-746810284 - `@nnethercote` I figured it out! It was simpler than I expected :)
This brings the size of `clean::Visibility` down from 40 bytes to 8.
Note that this does *not* remove `clean::Visibility`, even though it's now basically the same as `ty::Visibility`, because the `Invsible` variant means something different from `Inherited` and I thought it would be be confusing to merge the two. See the new comments on `impl Clean for ty::Visibility` for details.
Continue String to Symbol conversion in rustdoc (2)
Follow-up of #80119.
This is the last one (and I actually expected more conversions but seems like it was the last one remaining...).
r? `@jyn514`
Continue String to Symbol conversion in rustdoc
Follow-up of https://github.com/rust-lang/rust/pull/80091.
This PR is already big enough so I'll stop here before the next one.
r? `@jyn514`
Use more symbols in rustdoc
Builds on https://github.com/rust-lang/rust/pull/80044 and should not be merged before.
I want to test if this is actually faster before merging it, there was a lot of `to_string()` calls so I'm not sure it will actually help. That means I have to wait for 80044 to get merged before running perf.
r? `@ghost`
[rustdoc] Calculate span information on demand instead of storing it ahead of time
This brings `size_of<clean::types::Span>()` down from over 100 bytes (!!) to only 12, the same as rustc. It brings `Item` down even more, from `784` to `680`.
~~TODO: I need to figure out how to do this for the JSON backend too. That uses `From` impls everywhere, which don't allow passing in the `Session` as an argument. `@P1n3appl3,` `@tmandry,` maybe one of you have ideas?~~ Figured it out, fortunately only two functions needed to be changed. I like the `convert_x()` format better than `From` everywhere but I'm open to feedback.
Helps with #79103
Previously Markdown documentation was not rendered to HTML for search results,
which led to the output not being very readable, particularly for inline code.
This PR fixes that by rendering Markdown to HTML with the help of pulldown-cmark
(the library rustdoc uses to parse Markdown for the main text of documentation).
However, the text for the title attribute (the text shown when you hover over an
element) still uses the plain-text rendering since it is displayed in browsers
as plain-text.
Only these styles will be rendered; everything else is stripped away:
* *italics*
* **bold**
* `inline code`
Remove duplicate `Trait::auto` field
It was exactly the same as `is_auto`.
I found this while working on #78082, but it's not required for that PR.
r? `@GuillaumeGomez`
The main change is that `UnstableOptions::from_environment` now requires
an (optional) crate name. If the crate name is unknown (`None`), then the new feature is not available and you still have to use `RUSTC_BOOTSTRAP=1`. In practice this means the feature is only available for `--crate-name`, not for `#![crate_name]`; I'm interested in supporting the second but I'm not sure how.
Other major changes:
- Added `Session::is_nightly_build()`, which uses the `crate_name` of
the session
- Added `nightly_options::match_is_nightly_build`, a convenience method
for looking up `--crate-name` from CLI arguments.
`Session::is_nightly_build()`should be preferred where possible, since
it will take into account `#![crate_name]` (I think).
- Added `unstable_features` to `rustdoc::RenderOptions`
There is a user-facing change here: things like `RUSTC_BOOTSTRAP=0` no
longer active nightly features. In practice this shouldn't be a big
deal, since `RUSTC_BOOTSTRAP` is the opposite of stable and everyone
uses `RUSTC_BOOTSTRAP=1` anyway.
- Add tests
Check against `Cheat`, not whether nightly features are allowed.
Nightly features are always allowed on the nightly channel.
- Only call `is_nightly_build()` once within a function
- Use booleans consistently for rustc_incremental
Sessions can't be passed through threads, so `read_file` couldn't take a
session. To be consistent, also take a boolean in `write_file_header`.
This is mostly motivated by docs.rs. It's really weird
when arrow keys work in the top dropdown menu, but don't work
in other dropdown menus on the same page.
rustdoc has various user-configurable preferences. These are recorded
in web Local Storage (where available). But we want to provide a way
to configure the default default, including for when web storage is
not available.
getSettingValue is the function responsible for looking up these
settings. Here we make it fall back some in-DOM data, which
ultimately comes from RenderOptions.default_settings.
Using HTML data atrtributes is fairly convenient here, dsspite the
need to transform between snake and kebab case to avoid the DOM
converting kebab case to camel case (!)
We cache the element and dataset lookup in a global variable, to
ensure that getSettingValue remains fast.
The DOM representation has to be in an element which precedes the
inclusion of storage.js. That means it has to be in the <head> and we
should not use an empty <div> as the container (although most browsers
will accept that). An empty <script> element provides a convenient
and harmless container object. <meta> would be another possibility
but runs a greater risk of having unwanted behaviours on weird
browsers.
We trust the RenderOptions not to contain unhelpful setting names,
which don't fit nicely into an HTML attribute. It's awkward to quote
dataset keys.
Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>
Avoid extraneous space between visibility kw and ident for statics
Today, given a static like `static mut FOO: usize = 1`, rustdoc would
emit `static mut FOO: usize = 1`, as it emits both the mutability kw
with a space and reserves a space after the mutability kw. This patch
fixes that misformatting.
This patch also adds some tests for emit of other statics, as I could
not find an existing test devoted to statics.
Add settings to rustdoc to use the system theme
This PR adds new settings to `rustdoc` to use the operating system color scheme.
`rustdoc` actually had [basic support for this](b1af43bc63/src/librustdoc/html/static/storage.js (L121)), but the setting wasn't visible and couldn't be set back once the theme was explicitly set by the user. It also didn't update if the operating system theme preference changed while viewing a page.
I'm using [this method](https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries/Testing_media_queries#Receiving_query_notifications) to query and listen to changes to the `(prefers-color-scheme: dark)` media query. I kept the old method (based on `getComputedStyle`) as a fallback in case the user-agent doesn't support `window.matchMedia` (so like... [pretty much nobody](https://caniuse.com/?search=matchMedia)).
Since there's now more than one official ""dark"" theme in `rustdoc` (and also to support custom/third-party themes), the preferred dark and light themes can be configured in the settings page (the defaults are just "dark" and "light").
This is also my very first "proper" PR to Rust! Please let me know if I did anything wrong :).
Today, given a static like `static mut FOO: usize = 1`, rustdoc would
emit `static mut FOO: usize = 1`, as it emits both the mutability kw
with a space and reserves a space after the mutability kw. This patch
fixes that misformatting.
This patch also adds some tests for emit of other statics, as I could
not find an existing test devoted to statics.
For sub-items on a page don't show cfg that has already been rendered on
a parent item. At its simplest this means not showing anything that is
shown in the portability message at the top of the page, but also for
things like fields of an enum variant if that variant itself is
cfg-gated then don't repeat those cfg on each field of the variant.
This does not touch trait implementation rendering, as that is more
complex and there are existing issues around how it deals with doc-cfg
that need to be fixed first.
Remove disambiguators from intra doc link text
Closes https://github.com/rust-lang/rust/issues/65354.
r? @Manishearth
The commits are mostly atomic, but there might be some mix between them here and there. I recommend reading 'refactor ItemLink' and 'refactor RenderedLink' on their own though, lots of churn without any logic changes.
rustdoc: do not use plain summary for trait impls
Fixes#38386.
Fixes#48332.
Fixes#49430.
Fixes#62741.
Fixes#73474.
Unfortunately this is not quite ready to go because the newly-working links trigger a bunch of linkcheck failures. The failures are tough to fix because the links are resolved relative to the implementor, which could be anywhere in the module hierarchy.
(In the current docs, these links end up rendering as uninterpreted markdown syntax, so I don't think these failures are any worse than the status quo. It might be acceptable to just add them to the linkchecker whitelist.)
Ideally this could be fixed with intra-doc links ~~but it isn't working for me: I am currently investigating if it's possible to solve it this way.~~ Opened #73829.
EDIT: This is now ready!
Related to https://github.com/rust-lang/rust/issues/65354
- Pass through the replacement text to `markdown.rs`
- Add some tests
- Add a state machine that actually replaces the text when parsing Markdown
Fira Sans is what's used for module lists and other item lists.
Previously, the default body font, "Source Serif Pro", was used for
crate lists, which didn't visually match other item lists.
The old implementation only looks at numbers at the end, but not in
other places in a name: "u8" and "u16" got sorted properly, but "u8_bla"
and "u16_bla" did not.
