Scrape code examples from examples/ directory for Rustdoc

[willcrichton]

Adds support for the functionality described in rust-lang/rfcs#3123

Matching changes to Cargo are here: rust-lang/cargo#9525

Live demo here: https://willcrichton.net/example-analyzer/warp/trait.Filter.html#method.and

[rust-highfive]

Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez

[rust-highfive]

r? @GuillaumeGomez

(rust-highfive has picked a reviewer for you, use r? to override)

[bors]

☔ The latest upstream changes (presumably #86966) made this pull request unmergeable. Please resolve the merge conflicts.

[bors]

☔ The latest upstream changes (presumably #87269) made this pull request unmergeable. Please resolve the merge conflicts.

[camelid]

Please rebase over upstream changes instead of merging since rust-lang/rust has a "No-Merge Policy". Thanks!

[willcrichton]

@jyn514 I've done a significant cleanup of the PR and addressed some issues raised in the RFC. Notably:

• Links now go to rustdoc-generated files rather than an external repository.
• A lot of the highlighting logic has been pushed from the JS run-time to Rustdoc generation-time. I extended the highlighter to take custom decorations as input, which can insert the highlight into the HTML directly rather than after the page has rendered. The JS changes are now substantially smaller as a result.
• The number of examples for a given function has been capped, and further examples are just links to files (adding very little page weight).
• Rather than embedding the entire source of an example, I only embed the item enclosing the scraped call site. This further reduces page size.

I also tweaked the UI to make it more visually consistent and easier to use. I'll try to maintain a live demo here as I make changes: https://willcrichton.net/example-analyzer/warp/trait.Filter.html#method.and

I think it's ready for review, unless you (or others) have any big feature requests outstanding.

[camelid]

Two minor stylistic questions:

1. [+] More examples is currently in a serif font, whereas the rest of rustdoc usually uses sans-serif for these sorts of things.

2. Is it intentional that later uses in an example are highlighted in a slightly different color? For example:

   

[camelid]

A couple more UI comments:

1. I'd rather not have the blurred border at the edges of the examples; IMO it doesn't fit in with the rustdoc UI style.

2. The < and > arrows that are IIRC supposed to be in the top-right of the examples are not visible. I think this is because the DOM bounding boxes of the examples under [+] More examples extends too far to the right.

   EDIT: I think we decided in the RFC discussion that we should remove those errors in favor of just having a source link (at least for now). So I think they can be removed from the generated HTML.

[GuillaumeGomez]

Looks good to me!

@jyn514 @camelid Want to take a last look before approval?

[jyn514]

This is great, I'm really excited for it to land :) thank you @willcrichton for sticking with this so long! ❤️

[camelid]

I gave the code a quick look over to see if anything caught my eye. The main thing I'd like changed if possible is #85833 (comment). Other than that, I didn't notice anything major.

Like Joshua said, thank you for sticking with this!

[camelid]

I haven't looked at the code in detail, but Guillaume and Joshua have, so I don't have any more comments :)

[jyn514]

@bors r+ rollup=iffy

[bors]

📌 Commit fd5d614 has been approved by jyn514

[Mark-Simulacrum]

It looks like this was probably the cause of the regression in https://perf.rust-lang.org/compare.html?start=aa5740c715001f981515ed46faaddebf67cb9539&end=91b931926fd49fc97d1e39f2b8206abf1d77ce7d&stat=instructions:u, though it's a fairly minor one. May not be worth investigating too deeply, but marking as a perf-regression for the time being.

[willcrichton]

@Mark-Simulacrum this change does not trigger by default -- the examples have to be designed to pass in specific flags. I don't think this would affect existing benchmarks.

[jyn514]

@willcrichton the benchmarks are using the default settings, so the regression is real. It pointed to create_renderer, maybe something there is expensive?

That said, I agree this is probably not worth looking into, everything I saw was a one-time cost that should only matter for really tiny crates.