Skip to content

Improve Rustdoc scrape-examples UI#105387

Merged
bors merged 10 commits intorust-lang:masterfrom
willcrichton:scrape-examples-ui-improvements
Dec 9, 2022
Merged

Improve Rustdoc scrape-examples UI#105387
bors merged 10 commits intorust-lang:masterfrom
willcrichton:scrape-examples-ui-improvements

Conversation

@willcrichton
Copy link
Copy Markdown
Contributor

@willcrichton willcrichton commented Dec 6, 2022

This PR combines a few different improvements to the scrape-examples UI. See a live demo here: https://willcrichton.net/misc/scrape-examples/small-first-example/clap/struct.Arg.html

1. The first scraped example now takes up significantly less screen height.

Inserting the first scraped example takes up a lot of vertical screen space. I don't want this addition to overwhelm users, so I decided to reduce the height of the initial example in two ways: (A) the default un-expanded height is reduced from 240px (10 LOC) to 120px (5 LOC), and (B) the link to the example is now positioned over the example instead of atop the example (only on desktop though, not mobile). The changes to scrape-examples.js and rustdoc.css implement this fix.

Here is what an example docblock now looks like:

Screen Shot 2022-12-06 at 10 02 21 AM

2. Expanding all docblocks will not expand "More examples".

The "More examples blocks" are huge, so fully expanding everything on the page would take up too much vertical space. The changes to main.js implement this fix. This is tested in scrape-examples-toggle.goml.

3. Examples from binary crates are sorted higher than examples from library crates.

Code that is written as an example of an API is probably better for learning than code that happens to use an API, but isn't intended for pedagogic purposes. Unfortunately Rustc doesn't know whether a particular crate comes from an example target (only Cargo knows this). But we can at least create a proxy that prefers examples from binary crates over library crates, which we know from --crate-type.

This change is implemented by adding a new field bin_crate in Options (see config.rs). An is_bin field has been added to the scraped examples metadata (see scrape_examples.rs). Then the example sorting metric uses is_bin as the first entry of a lexicographic sort on (is_bin, example_size, display_name) (see render/mod.rs).

Note that in the future we can consider adding another flag like --scrape-examples-cargo-target that would pass target information from Cargo into the example metadata. But I'm proposing a less intrusive change for now.

4. The scrape-examples help page has been updated to reflect the latest Cargo interface.

See scrape-examples-help.md.

r? @notriddle

P.S. once this PR and rust-lang/cargo#11450 are merged, then I think the scrape-examples feature is officially ready for deployment on docs.rs!

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

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.

7 participants