Improve Rustdoc UI for scraped examples with multiline arguments, fix overflow in line numbers #93217

willcrichton · 2022-01-22T23:35:57Z

This PR improves a few aspects of the scrape examples feature in Rustdoc.

Only function names and not the full call expression are highlighted.
For call-sites with multiline arguments, the minimized code viewer will scroll to the top of the call-site rather than the middle if the argument is larger than the viewer size, ensuring that the function name is visible.
This fixes an issue where the line numbers column had a visible x-scroll bar.

r? @GuillaumeGomez

rust-highfive · 2022-01-22T23:36:00Z

Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez,@Folyd

src/librustdoc/scrape_examples.rs

src/librustdoc/html/render/mod.rs

src/doc/rustdoc/src/scraped-examples.md

camelid · 2022-01-31T02:16:50Z

Please move the --test commit to a new PR. It's a separate issue from improving the UI.

camelid · 2022-01-31T02:17:32Z

I think that change would also require an FCP and more discussion.

willcrichton · 2022-01-31T05:40:58Z

Ok, I pulled that change into #93497.

bors · 2022-01-31T14:30:35Z

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

GuillaumeGomez · 2022-02-01T23:44:55Z

src/librustdoc/html/render/mod.rs

@@ -2577,7 +2578,9 @@ fn render_call_locations(w: &mut Buffer, cx: &Context<'_>, item: &clean::Item) {
          <span></span>\
          <h5 id=\"{id}\" class=\"section-header\">\
             <a href=\"#{id}\">Examples found in repository</a>\
+             <a class=\"scrape-help\" href=\"{doc_prefix}/rustdoc/scraped-examples.html\" target=\"_blank\">?</a>\


I think this is way too much:

It's pretty obvious what this is.

It'll increase the page size once more for a very minor gain.

cc @jsha and @camelid who have thoughts on this

I really don't think we should be worrying about a small increase in page size like this. And I don't think it's that obvious what it is. For you, it may be obvious, since you've been immersed in this feature throughout its development, but most users have never even heard of it.

Even if they don't know about the feature, the text itself is pretty explicit: "Examples found in...". The rustdoc book exists and will include a chapter about this but I don't think there is enough interest for it.

Also, it's definitely not a small increase in page size. Especially on big crates with a lot of methods.

The rustdoc book exists and will include a chapter about this but I don't think there is enough interest for it.

I'm not sure what you mean about interest.

If we're going to have an explainer in the docs that's distinct from the chapter in the rustdoc book, it should probably just be an overlay / popup like the current help menu. It wouldn't be more than a couple sentences probably.

@jsha @GuillaumeGomez can y'all let me know what your final preference is for the scrape examples help message? I'd like to implement it this weekend.

Writing a page and linking to it based on what @jsha suggested.

Is it ok if I implement it as a popup though? I really think that would be both a better user experience and simpler for me to implement.

Simpler I'm not sure. Adding an HTML page should be quite easy. Then you just have to link to it. Adding more JS for this doesn't seem the best solution but maybe I'm wrong?

src/librustdoc/html/render/mod.rs

bors · 2022-02-08T10:09:22Z

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

bors · 2022-02-10T15:34:07Z

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

… help page

willcrichton · 2022-03-28T01:23:12Z

Alright, well if it's good as is, are there any last requests on this PR? @jsha @GuillaumeGomez @camelid

willcrichton · 2022-04-05T02:21:08Z

@rustbot ready

camelid · 2022-04-07T19:38:46Z

The effects of this change as listed in the PR description sound good to me; I'll leave reviewing the code to Guillaume.

GuillaumeGomez · 2022-04-12T11:04:20Z

src/librustdoc/html/static/scrape-examples-help.md

+
+1. For a given item, a maximum of 5 examples are included in the page. The remaining examples are just links to source code.
+2. Only one example is shown by default, and the remaining examples are hidden behind a toggle.
+3. For a given file that contains examples, only the item containing the examples will be included in the generated documentation.


Can you add a new section at the end providing a link to the rustdoc book chapter talking about this feature please? Something like:

## Official tutorial If you want more information about this feature, take a look at the [rustdoc book chapter](link here).

Just added a commit for this. It looks like:

GuillaumeGomez · 2022-04-12T11:04:40Z

Apart from my comment, looks all good to me!

locations in scrape examples.

willcrichton · 2022-04-12T18:08:15Z

Note: I also just added a commit which removes the remaining unwraps in scrape_examples.rs to harden the scraping phase. I would like to make sure that once this feature rolls out, people encounter issues as "my example isn't being scraped" rather than "rustdoc is panicking".

GuillaumeGomez · 2022-04-13T15:20:28Z

src/librustdoc/html/render/mod.rs

    let mut ids = IdMap::default();
    format!(
-        "<div class=\"main-heading\">
+        "<div class=\"main-heading\">\


GuillaumeGomez · 2022-04-13T15:22:18Z

All good for me. Then let's go!

@bors: r+

bors · 2022-04-13T15:22:20Z

📌 Commit 6a18b68 has been approved by GuillaumeGomez

Rollup of 6 pull requests Successful merges: - rust-lang#93217 (Improve Rustdoc UI for scraped examples with multiline arguments, fix overflow in line numbers) - rust-lang#95885 (Improve error message in case of missing checksum) - rust-lang#95962 (Document that DirEntry holds the directory open) - rust-lang#95991 (fix: wrong trait import suggestion for T:) - rust-lang#96005 (Add missing article to fix "few" to "a few".) - rust-lang#96006 (Add a missing article) Failed merges: r? `@ghost` `@rustbot` modify labels: rollup

rust-highfive assigned GuillaumeGomez Jan 22, 2022

rustbot added the T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. label Jan 22, 2022

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jan 22, 2022

willcrichton mentioned this pull request Jan 22, 2022

Tracking Issue for RFC 3123: Scrape code examples from examples/ directory for Rustdoc #88791

Open

4 tasks

willcrichton force-pushed the example-analyzer branch from 295bbbf to 1407067 Compare January 25, 2022 01:32

camelid self-assigned this Jan 25, 2022

camelid reviewed Jan 25, 2022

View reviewed changes

src/librustdoc/scrape_examples.rs Outdated Show resolved Hide resolved

camelid added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jan 25, 2022

willcrichton force-pushed the example-analyzer branch from ed4aff1 to 66e3208 Compare January 28, 2022 01:00

camelid reviewed Jan 28, 2022

View reviewed changes

src/librustdoc/html/render/mod.rs Outdated Show resolved Hide resolved

This comment has been minimized.

Sign in to view

camelid reviewed Jan 28, 2022

View reviewed changes

src/doc/rustdoc/src/scraped-examples.md Show resolved Hide resolved

This comment has been minimized.

Sign in to view

willcrichton force-pushed the example-analyzer branch from 37a312f to 935f112 Compare January 30, 2022 23:40

willcrichton mentioned this pull request Jan 30, 2022

Change rustdoc-scrape-examples to be a target-level configuration rust-lang/cargo#10343

Merged

willcrichton force-pushed the example-analyzer branch from 935f112 to 9b94c26 Compare January 31, 2022 05:35

willcrichton force-pushed the example-analyzer branch from 9b94c26 to dc9c17b Compare January 31, 2022 19:05

GuillaumeGomez reviewed Feb 1, 2022

View reviewed changes

src/librustdoc/html/render/mod.rs Show resolved Hide resolved

willcrichton force-pushed the example-analyzer branch from dc9c17b to fa0719a Compare February 8, 2022 20:18

willcrichton force-pushed the example-analyzer branch from fa0719a to dca7ceb Compare February 13, 2022 01:24

willcrichton added 7 commits March 27, 2022 18:10

Only highlight identifier in scraped examples, not arguments

d58c9df

Use PathSegment::ident for scraping method calls

f1e3e2c

Improve alignment of additional scraped examples, add scrape examples…

ae5d0cb

… help page

Fix markdown issue, remove hard-coded rust-lang.org url

7cca693

Improve styling on scrape examples help button

bb3ed6f

Clarify that scrape examples is unstable

318e457

Add scrape examples help page

d1416d5

willcrichton force-pushed the example-analyzer branch from 2aa8381 to d1416d5 Compare March 28, 2022 01:22

Don't panic when scraping invalid calls

b9ecdca

willcrichton mentioned this pull request Mar 28, 2022

ICE when using rustdoc-scrape-examples on example that uses proc macros #94926

Closed

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Apr 5, 2022

camelid removed their assignment Apr 7, 2022

GuillaumeGomez reviewed Apr 12, 2022

View reviewed changes

Add Rustdoc book link to scrape examples help. Remove remaining panic

6a18b68

locations in scrape examples.

GuillaumeGomez reviewed Apr 13, 2022

View reviewed changes

GuillaumeGomez approved these changes Apr 13, 2022

View reviewed changes

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 Apr 13, 2022

Dylan-DPC mentioned this pull request Apr 13, 2022

Rollup of 6 pull requests #96015

Merged

bors merged commit db61452 into rust-lang:master Apr 13, 2022

rustbot added this to the 1.62.0 milestone Apr 13, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve Rustdoc UI for scraped examples with multiline arguments, fix overflow in line numbers #93217

Improve Rustdoc UI for scraped examples with multiline arguments, fix overflow in line numbers #93217

willcrichton commented Jan 22, 2022 •

edited

Loading

rust-highfive commented Jan 22, 2022

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

camelid commented Jan 31, 2022

camelid commented Jan 31, 2022

willcrichton commented Jan 31, 2022

bors commented Jan 31, 2022

GuillaumeGomez Feb 1, 2022

willcrichton Feb 1, 2022

camelid Feb 3, 2022

GuillaumeGomez Feb 3, 2022

camelid Feb 3, 2022

willcrichton Feb 7, 2022

willcrichton Feb 13, 2022

GuillaumeGomez Feb 13, 2022

willcrichton Feb 13, 2022

GuillaumeGomez Feb 14, 2022

bors commented Feb 8, 2022

bors commented Feb 10, 2022

willcrichton commented Mar 28, 2022

willcrichton commented Apr 5, 2022

camelid commented Apr 7, 2022

GuillaumeGomez Apr 12, 2022

willcrichton Apr 12, 2022

GuillaumeGomez commented Apr 12, 2022

willcrichton commented Apr 12, 2022

GuillaumeGomez Apr 13, 2022

GuillaumeGomez commented Apr 13, 2022

bors commented Apr 13, 2022

Improve Rustdoc UI for scraped examples with multiline arguments, fix overflow in line numbers #93217

Improve Rustdoc UI for scraped examples with multiline arguments, fix overflow in line numbers #93217

Conversation

willcrichton commented Jan 22, 2022 • edited Loading

rust-highfive commented Jan 22, 2022

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

camelid commented Jan 31, 2022

camelid commented Jan 31, 2022

willcrichton commented Jan 31, 2022

bors commented Jan 31, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bors commented Feb 8, 2022

bors commented Feb 10, 2022

willcrichton commented Mar 28, 2022

willcrichton commented Apr 5, 2022

camelid commented Apr 7, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

GuillaumeGomez commented Apr 12, 2022

willcrichton commented Apr 12, 2022

Choose a reason for hiding this comment

GuillaumeGomez commented Apr 13, 2022

bors commented Apr 13, 2022

willcrichton commented Jan 22, 2022 •

edited

Loading