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.
Inhibit clicks on summary's children
A byproduct of using `<details>` and `<summary>` to show/hide detailed documentation was that clicking any part of a method heading (or impl heading) would show or hide the documentation. This was not super noticeable because clicking a link inside the method heading would navigate to that link. But clicking any unlinked black text in a method heading would trigger the behavior.
That behavior was somewhat unexpected, and means that if you try to click a type name in a method heading, but miss by a few pixels, you get a confusing surprise.
This change inhibits that behavior by putting an event listener on most summaries that cancels the event unless the event target was the summary itself. In practice, that means it cancels the event unless the target was the "[+]" / "[-]", because the rest of the heading is wrapped inside a `<div>`, which is the target for anything that doesn't have a more specific target.
r? ``@Manishearth``
Set color for <a> in a more straightforward way.
Previously, we set the default color for <a> tags to black, and then had an override with a bunch of not() clauses to set anchors in
docblocks to blue.
Instead, we should set the default color for <a> to blue (or equivalent in other themes), and override it for places like the sidebar or search results, where we don't want them to be styled as links.
Demo at https://rustdoc.crud.net/jsha/theme-anchor/std/string/struct.String.html. This should result in no visible changes.
r? `@GuillaumeGomez`
Previously, we set the default color for <a> tags to black, and then
had an override with a bunch of not() clauses to set anchors in
docblocks to blue.
Instead, we should set the default color for <a> to blue (or equivalent
in other themes), and override it for places like the sidebar or search
results, where we don't want them to be styled as links.
A byproduct of using `<details>` and `<summary>` to show/hide detailed
documentation was that clicking any part of a method heading (or impl
heading) would show or hide the documentation. This was not super
noticeable because clicking a link inside the method heading would
navigate to that link. But clicking any unlinked black text in a method
heading would trigger the behavior.
That behavior was somewhat unexpected, and means that if you try to click
a type name in a method heading, but miss by a few pixels, you get a
confusing surprise.
This change inhibits that behavior by putting an event listener on most
summaries that cancels the event unless the event target was the summary
itself. In practice, that means it cancels the event unless the target
was the "[+]" / "[-]", because the rest of the heading is wrapped inside
a `<div>`, which is the target for anything that doesn't have a more
specific target.
Make scrollbar in the sidebar always visible for visual consistency
Fixes#90943.
I had to add a background in `dark` and `ayu` themes, otherwise it was looking strange (like an invisible margin). So it looks like this:
Sadly, I wasn't able to add a GUI test to ensure that the scrollbar was always displayed because it seems not possible in puppeteer for whatever reason... I used this method: on small pages (like `lib2/sub_mod/index.html`), comparing `.navbar`'s `clientWidth` with `offsetWidth` (the first doesn't include the sidebar in the computed amount). When checking in the browser, it works fine but in puppeteer it almost never works...
In case anyone want to try to solve the bug, here is the puppeteer code:
<details>
More information about this: I tried another approach which was to get the element in `evaluate` directly (by calling it from `page.evaluate(() => { .. });` directly instead of `parseAssertElemProp.evaluate(e => {...});`.
```js
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto("file:///path/rust/build/x86_64-unknown-linux-gnu/test/rustdoc-gui/doc/lib2/sub_mod/index.html");
await page.waitFor(".sidebar");
let parseAssertElemProp = await page.$(".sidebar");
if (parseAssertElemProp === null) { throw '".sidebar" not found'; }
await parseAssertElemProp.evaluate(e => {
const parseAssertElemPropDict = {"clientWidth": "192", "offsetWidth":"200"};
for (const [parseAssertElemPropKey, parseAssertElemPropValue] of Object.entries(parseAssertElemPropDict)) {
if (e[parseAssertElemPropKey] === undefined || String(e[parseAssertElemPropKey]) != parseAssertElemPropValue) {
throw 'expected `' + parseAssertElemPropValue + '` for property `' + parseAssertElemPropKey + '` for selector `.sidebar`, found `' + e[parseAssertElemPropKey] + '`';
}
}
}).catch(e => console.error(e));
await browser.close();
})();
```
</details>
r? ``@jsha``
- Remove border.
- Reduce size of emoji slightly.
- Remove details disclosure for unstable reason. This was inconsistent
with our other details disclosures, and the detail revealed was
usually better explained by clicking on the issue link.
Remove unneeded FIXMEs comments in search index generation
Original comment:
> Instead of recreating a new `vec` for each arguments, we re-use the same. The impact on performance should be minor but worth a try.
After testing it, we reached the conclusion that the code readability drop wasn't worth the almost unnoticeable performance improvement.
r? `@camelid`
Add more comments to explain the code to generate the search index
Fixes#90766.
I tried to put comments when the code wasn't easy to understand at first sight and added more documentation on the recursive function. Please tell me if I misused the terminology or if comments can be improved or added into other places.
r? `@notriddle`
This change has two advantages:
1. It makes the possible states clearer, and it makes it impossible to
construct invalid states, such as a blanket impl that is also an auto
trait impl.
2. It shrinks the size of `Impl` a bit, since now there is only one
field, rather than two.
Fix ICE when rustdoc is scraping examples inside of a proc macro
This PR provides a clearer semantics for how --scrape-examples interacts with macros. If an expression's span AND it's enclosing item's span both are not `from_expansion`, then the example will be scraped. The added test case `rustdoc-scrape-examples-macros` shows a variety of situations.
* A macro-rules macro that takes a function call as input: good
* A macro-rules macro that generates a function call as output: bad
* A proc-macro that generates a function call as output: bad
* An attribute macro that generates a function call as output: bad
* An attribute macro that takes a function call as input: good, if the proc macro is designed to propagate the input spans
I ran this updated rustdoc on pyo3 and confirmed that it successfully scrapes examples from inside a proc macro, eg
<img width="1013" alt="Screen Shot 2021-11-04 at 1 11 28 PM" src="https://user-images.githubusercontent.com/663326/140412691-81a3bb6b-a448-4a1b-a293-f7a795553634.png">
(cc `@mejrs)`
Additionally, this PR fixes an ordering bug in the highlighting logic.
Fixes https://github.com/rust-lang/rust/issues/90567.
r? `@jyn514`
rustdoc: Add `DocVisitor` and use it where possible
`DocFolder` allows transforming the docs, accomplished by making its methods take and return types by-value. However, several of the rustdoc `DocFolder` impls only *visit* the docs; they don't change anything. Passing around types by-value is thus unnecessary, confusing, and potentially inefficient for those impls.
`DocVisitor` is very similar to `DocFolder`, except that its methods take shared references and return nothing (i.e., the unit type). This should both be more efficient and make the code clearer.
There is an additional reason to add `DocVisitor`, too. As part of my cleanup of `external_traits`, I'm planning to add a `fn cache(&mut self) -> &mut Cache` method to `DocFolder` so that `external_traits` can be retrieved explicitly from the `Cache`, rather than implicitly via `Crate.external_traits` (which is an `Rc<RefCell<...>>`). However, some of the `DocFolder` impls that could be turned into `DocVisitor` impls only have a shared reference to the `Cache`, because they are used during rendering. (They have to access the `Cache` via `html::render::Context.shared.cache`, which involves an `Rc`.)
Since `DocVisitor` does not mutate any of the types it's visiting, its equivalent `cache()` method will only need a shared reference to the `Cache`, avoiding the problem described above.
r? `@GuillaumeGomez`
cc `@jyn514`
* Flip conjuncts of `&&` in rustdoc
The `CrateNum` comparison should be very cheap, while
`span.filename()` fetches and clones a `FileName`.
* Use `into_local_path()` instead of `local_path().clone()`
rustdoc: Compute some fields of `clean::Crate` on-demand to reduce size
`clean::Crate` is frequently moved by-value -- for example, in `DocFolder`
implementations -- so reducing its size should improve performance.
This PR reduces the size of `clean::Crate` from 168 bytes to 104 bytes.
r? `@jyn514`
