Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Scrape code examples from examples/ directory for Rustdoc #85833

Merged
merged 24 commits into from
Oct 23, 2021

Conversation

willcrichton
Copy link
Contributor

@willcrichton willcrichton commented May 30, 2021

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
Copy link
Collaborator

Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez

@rust-highfive
Copy link
Collaborator

r? @GuillaumeGomez

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

@rust-log-analyzer

This comment has been minimized.

@rust-log-analyzer

This comment has been minimized.

@rust-log-analyzer

This comment has been minimized.

src/librustdoc/config.rs Outdated Show resolved Hide resolved
@rust-log-analyzer

This comment has been minimized.

@bors

This comment has been minimized.

@bors
Copy link
Contributor

bors commented Jul 8, 2021

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

@bors
Copy link
Contributor

bors commented Jul 19, 2021

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

@inquisitivecrystal inquisitivecrystal added the T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. label Aug 24, 2021
@rust-log-analyzer

This comment has been minimized.

@rust-log-analyzer

This comment has been minimized.

@rust-log-analyzer

This comment has been minimized.

@rust-log-analyzer

This comment has been minimized.

@rust-log-analyzer

This comment has been minimized.

@BubbaSheen
This comment has been minimized.
@rust-log-analyzer

This comment has been minimized.

@camelid
Copy link
Member

camelid commented Sep 13, 2021

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

@willcrichton
Copy link
Contributor Author

@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
Copy link
Member

camelid commented Sep 14, 2021

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:

    image

@camelid
Copy link
Member

camelid commented Sep 14, 2021

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
Copy link
Member

Looks good to me!

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

Copy link
Member

@jyn514 jyn514 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

src/doc/rustdoc/src/unstable-features.md Outdated Show resolved Hide resolved
src/librustdoc/clean/types.rs Outdated Show resolved Hide resolved
@camelid
Copy link
Member

camelid commented Oct 20, 2021

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
Copy link
Member

camelid commented Oct 22, 2021

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

@jyn514
Copy link
Member

jyn514 commented Oct 23, 2021

@bors r+ rollup=iffy

@bors
Copy link
Contributor

bors commented Oct 23, 2021

📌 Commit fd5d614 has been approved by jyn514

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Oct 23, 2021
matthiaskrgr added a commit to matthiaskrgr/rust that referenced this pull request Oct 23, 2021
…n514

Scrape code examples from examples/ directory for Rustdoc

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
bors added a commit to rust-lang-ci/rust that referenced this pull request Oct 23, 2021
…askrgr

Rollup of 5 pull requests

Successful merges:

 - rust-lang#85833 (Scrape code examples from examples/ directory for Rustdoc)
 - rust-lang#88041 (Make all proc-macro back-compat lints deny-by-default)
 - rust-lang#89829 (Consider types appearing in const expressions to be invariant)
 - rust-lang#90168 (Reset qualifs when a storage of a local ends)
 - rust-lang#90198 (Add caveat about changing parallelism and function call overhead)

Failed merges:

r? `@ghost`
`@rustbot` modify labels: rollup
@bors bors merged commit dcf9242 into rust-lang:master Oct 23, 2021
@rustbot rustbot added this to the 1.58.0 milestone Oct 23, 2021
@Mark-Simulacrum
Copy link
Member

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.

@Mark-Simulacrum Mark-Simulacrum added the perf-regression Performance regression. label Oct 26, 2021
@jyn514 jyn514 deleted the example-analyzer branch October 26, 2021 16:20
@willcrichton
Copy link
Contributor Author

@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
Copy link
Member

jyn514 commented Oct 26, 2021

@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.

bors added a commit to rust-lang/cargo that referenced this pull request Oct 28, 2021
Scrape code examples from examples/ directory for Rustdoc

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

Matching changes to rustdoc are here: rust-lang/rust#85833
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
perf-regression Performance regression. requires-nightly This issue requires a nightly compiler in some way. S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

Successfully merging this pull request may close these issues.