https://github.com/rust-lang/rust http://git.dreamy.place/mirrors/rust/atom?h=1.67.0 2022-12-09T06:25:46+00:00 2022-12-09T06:25:46+00:00 Matthias Krüger matthias.krueger@famsik.de 2022-12-09T06:25:46+00:00 urn:sha1:441669c382298661db59cdf4374dbd40ab75b222 rustdoc: clean up docblock table CSS # Preview http://notriddle.com/notriddle-rustdoc-demos/table-2/test_dingus/fn.test.html # Before  # After  # Details * The rule `display: block` had no noticeable effect. Technically, because markdown tables have a tbody and thead, they get wrapped in an [anonymous table box] in the CSS tree, nested within the `<table>` element's block layout box. This rule was added in #87230 to make the table side-scrolling, but this same issue was doubly fixed in #88742 by wrapping it in an explicit `<div>` tag. Since accessibility advocates recommend the wrapper div over marking the table as `display: block`, we'll stick with that. https://adrianroselli.com/2020/11/under-engineered-responsive-tables.html * The rule `width: calc(100% - 2px)` had no visible effect, because the anonymous table box was not affected. * The style is tweaked to basically be the same style GitHub uses. In particular, it adds zebra stripes, and removes dotted borders. https://rust-lang.zulipchat.com/#narrow/stream/266220-rustdoc/topic/Markdown.20table.20styling [anonymous table box]: https://www.w3.org/TR/CSS2/tables.html#anonymous-boxes 2022-12-09T06:25:44+00:00 Matthias Krüger matthias.krueger@famsik.de 2022-12-09T06:25:44+00:00 urn:sha1:5fd540b8fe1a131b1e00b5b147c52d5ba15a7210 Improve Rustdoc scrape-examples UI 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:  ### 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! 2022-12-08T17:37:03+00:00 Michael Howell michael@notriddle.com 2022-12-08T16:38:27+00:00 urn:sha1:34700f6594436b49005151ee12dd2ae06c7cad03 2022-12-08T05:49:10+00:00 Michael Howell michael@notriddle.com 2022-12-08T04:59:54+00:00 urn:sha1:a09e8c55c663d2b070f99ab0fdadbcc2c45656b2 * The rule `display: block` had no noticeable effect. Technically, because markdown tables have a tbody and thead, they get wrapped in an [anonymous table box] in the CSS tree, nested within the `<table>` element's block layout box. This rule was added in #87230 to make the table side-scrolling, but this same issue was doubly fixed in #88742 by wrapping it in an explicit `<div>` tag. Since accessibility advocates recommend the wrapper div over marking the table as `display: block`, we'll stick with that. https://adrianroselli.com/2020/11/under-engineered-responsive-tables.html * The rule `width: calc(100% - 2px)` had no visible effect, because the anonymous table box was not affected. * The style is tweaked to basically be the same style GitHub uses. In particular, it adds zebra stripes, and removes dotted borders. [anonymous table box]: https://www.w3.org/TR/CSS2/tables.html#anonymous-boxes 2022-12-07T18:42:09+00:00 Will Crichton wcrichto@cs.stanford.edu 2022-12-07T18:24:16+00:00 urn:sha1:9499d2cce3bebef96d8ae64442602f87726a875a 2022-12-07T17:08:43+00:00 Will Crichton wcrichto@cs.stanford.edu 2022-12-06T19:24:26+00:00 urn:sha1:0709e534df2a85486f981bfbebd153bb25e3703d 2022-12-07T17:08:43+00:00 Will Crichton wcrichto@cs.stanford.edu 2022-12-06T17:34:37+00:00 urn:sha1:679d7ea064491dfc8d067fcef07827e7569a093e 2022-12-07T17:08:43+00:00 Will Crichton wcrichto@cs.stanford.edu 2022-12-06T07:48:07+00:00 urn:sha1:45742170741d6c6b9abda5fc51012a01ce1c704a 2022-12-07T17:08:43+00:00 Will Crichton wcrichto@cs.stanford.edu 2022-11-27T19:11:21+00:00 urn:sha1:6ccd14a782420d27aef9d9fcd9196949a3276427 * Examples take up less screen height. * Snippets from binary crates are prioritized. * toggle-all-docs does not expand "More examples" sections. 2022-12-07T14:39:09+00:00 Matthias Krüger matthias.krueger@famsik.de 2022-12-07T14:39:09+00:00 urn:sha1:c75478b2460677141e8668fc69669e19d4a6584c rustdoc: simplify CSS selectors for item table `.stab` The module-item and import-item classes are attached to the item-left. Just target that, instead.