Skip to content

Commit 85b69bf

Browse files
matthiaskrgrmatthiaskrgr
authored
Rollup merge of #135641 - GuillaumeGomez:items-list, r=notriddle
[rustdoc] Replace module list items `ul`/`li` with `dl`/`dd`/`dt` elements `@hywan` suggested that rustdoc should use `dl`,`dt` and `dd` HTML tags for listing items on module pages as it matches better what this is (an item and optionally its description). This is a very good idea so here is the implementation. Also nice side-effect of this change: it reduces a bit the generated HTML since we go from: This PR shouldn't impact page appearance. ```html <ul class="item-table"> <li> <div class="item-name">NAME</div> <div class="desc docblock-short">THE DOC</div> </li> </ul> ``` to: ```html <dl class="item-table"> <dt>NAME</dt> <dd>THE DOC</dd> </dl> ``` You can test it [here](https://rustdoc.crud.net/imperio/items-list/std/index.html). r? `@notriddle`
2 parents 1d55f72 + b3865d1 commit 85b69bf

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

47 files changed

+185
-221
lines changed

‎src/librustdoc/html/render/print_item.rs

Lines changed: 17 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -140,10 +140,9 @@ macro_rules! item_template_methods {
140140
};
141141
}
142142

143-
const ITEM_TABLE_OPEN: &str = "<ul class=\"item-table\">";
144-
const ITEM_TABLE_CLOSE: &str = "</ul>";
145-
const ITEM_TABLE_ROW_OPEN: &str = "<li>";
146-
const ITEM_TABLE_ROW_CLOSE: &str = "</li>";
143+
const ITEM_TABLE_OPEN: &str = "<dl class=\"item-table\">";
144+
const REEXPORTS_TABLE_OPEN: &str = "<dl class=\"item-table reexports\">";
145+
const ITEM_TABLE_CLOSE: &str = "</dl>";
147146

148147
// A component in a `use` path, like `string` in std::string::ToString
149148
struct PathComponent {
@@ -400,66 +399,53 @@ fn item_module(w: &mut Buffer, cx: &Context<'_>, item: &clean::Item, items: &[cl
400399
w.write_str(ITEM_TABLE_CLOSE);
401400
}
402401
last_section = Some(my_section);
403-
write_section_heading(
404-
w,
405-
my_section.name(),
406-
&cx.derive_id(my_section.id()),
407-
None,
408-
ITEM_TABLE_OPEN,
409-
);
402+
let section_id = my_section.id();
403+
let tag =
404+
if section_id == "reexports" { REEXPORTS_TABLE_OPEN } else { ITEM_TABLE_OPEN };
405+
write_section_heading(w, my_section.name(), &cx.derive_id(section_id), None, tag);
410406
}
411407

412408
match myitem.kind {
413409
clean::ExternCrateItem { ref src } => {
414410
use crate::html::format::anchor;
415411

416-
w.write_str(ITEM_TABLE_ROW_OPEN);
417412
match *src {
418413
Some(src) => write!(
419414
w,
420-
"<div class=\"item-name\"><code>{}extern crate {} as {};",
415+
"<dt><code>{}extern crate {} as {};",
421416
visibility_print_with_space(myitem, cx),
422417
anchor(myitem.item_id.expect_def_id(), src, cx),
423418
EscapeBodyTextWithWbr(myitem.name.unwrap().as_str()),
424419
),
425420
None => write!(
426421
w,
427-
"<div class=\"item-name\"><code>{}extern crate {};",
422+
"<dt><code>{}extern crate {};",
428423
visibility_print_with_space(myitem, cx),
429424
anchor(myitem.item_id.expect_def_id(), myitem.name.unwrap(), cx),
430425
),
431426
}
432-
w.write_str("</code></div>");
433-
w.write_str(ITEM_TABLE_ROW_CLOSE);
427+
w.write_str("</code></dt>");
434428
}
435429

436430
clean::ImportItem(ref import) => {
437431
let stab_tags = import.source.did.map_or_else(String::new, |import_def_id| {
438432
extra_info_tags(tcx, myitem, item, Some(import_def_id)).to_string()
439433
});
440434

441-
w.write_str(ITEM_TABLE_ROW_OPEN);
442435
let id = match import.kind {
443436
clean::ImportKind::Simple(s) => {
444437
format!(" id=\"{}\"", cx.derive_id(format!("reexport.{s}")))
445438
}
446439
clean::ImportKind::Glob => String::new(),
447440
};
448-
let (stab_tags_before, stab_tags_after) = if stab_tags.is_empty() {
449-
("", "")
450-
} else {
451-
("<div class=\"desc docblock-short\">", "</div>")
452-
};
453441
write!(
454442
w,
455-
"<div class=\"item-name\"{id}>\
456-
<code>{vis}{imp}</code>\
457-
</div>\
458-
{stab_tags_before}{stab_tags}{stab_tags_after}",
443+
"<dt{id}>\
444+
<code>{vis}{imp}</code>{stab_tags}\
445+
</dt>",
459446
vis = visibility_print_with_space(myitem, cx),
460447
imp = import.print(cx),
461448
);
462-
w.write_str(ITEM_TABLE_ROW_CLOSE);
463449
}
464450

465451
_ => {
@@ -492,22 +478,18 @@ fn item_module(w: &mut Buffer, cx: &Context<'_>, item: &clean::Item, items: &[cl
492478
_ => "",
493479
};
494480

495-
w.write_str(ITEM_TABLE_ROW_OPEN);
496481
let docs =
497482
MarkdownSummaryLine(&myitem.doc_value(), &myitem.links(cx)).into_string();
498-
let (docs_before, docs_after) = if docs.is_empty() {
499-
("", "")
500-
} else {
501-
("<div class=\"desc docblock-short\">", "</div>")
502-
};
483+
let (docs_before, docs_after) =
484+
if docs.is_empty() { ("", "") } else { ("<dd>", "</dd>") };
503485
write!(
504486
w,
505-
"<div class=\"item-name\">\
487+
"<dt>\
506488
<a class=\"{class}\" href=\"{href}\" title=\"{title}\">{name}</a>\
507489
{visibility_and_hidden}\
508490
{unsafety_flag}\
509491
{stab_tags}\
510-
</div>\
492+
</dt>\
511493
{docs_before}{docs}{docs_after}",
512494
name = EscapeBodyTextWithWbr(myitem.name.unwrap().as_str()),
513495
visibility_and_hidden = visibility_and_hidden,
@@ -521,7 +503,6 @@ fn item_module(w: &mut Buffer, cx: &Context<'_>, item: &clean::Item, items: &[cl
521503
.collect::<Vec<_>>()
522504
.join(" "),
523505
);
524-
w.write_str(ITEM_TABLE_ROW_CLOSE);
525506
}
526507
}
527508
}

‎src/librustdoc/html/static/css/rustdoc.css

Lines changed: 27 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -242,7 +242,7 @@ h1, h2, h3, h4, h5, h6,
242242
.mobile-topbar,
243243
.search-input,
244244
.search-results .result-name,
245-
.item-name > a,
245+
.item-table dt > a,
246246
.out-of-band,
247247
.sub-heading,
248248
span.since,
@@ -385,11 +385,11 @@ details:not(.toggle) summary {
385385
code, pre, .code-header, .type-signature {
386386
font-family: "Source Code Pro", monospace;
387387
}
388-
.docblock code, .docblock-short code {
388+
.docblock code, .item-table dd code {
389389
border-radius: 3px;
390390
padding: 0 0.125em;
391391
}
392-
.docblock pre code, .docblock-short pre code {
392+
.docblock pre code, .item-table dd pre code {
393393
padding: 0;
394394
}
395395
pre {
@@ -887,13 +887,13 @@ both the code example and the line numbers, so we need to remove the radius in t
887887
text-align: center;
888888
}
889889

890-
.docblock-short {
890+
.item-table dd {
891891
overflow-wrap: break-word;
892892
overflow-wrap: anywhere;
893893
}
894894
/* Wrap non-pre code blocks (`text`) but not (```text```). */
895895
.docblock :not(pre) > code,
896-
.docblock-short code {
896+
.item-table dd code {
897897
white-space: pre-wrap;
898898
}
899899

@@ -938,7 +938,7 @@ rustdoc-toolbar {
938938
min-height: 60px;
939939
}
940940

941-
.docblock code, .docblock-short code,
941+
.docblock code, .item-table dd code,
942942
pre, .rustdoc.src .example-wrap, .example-wrap .src-line-numbers {
943943
background-color: var(--code-block-background-color);
944944
border-radius: var(--code-block-border-radius);
@@ -964,7 +964,7 @@ pre, .rustdoc.src .example-wrap, .example-wrap .src-line-numbers {
964964
background: var(--table-alt-row-background-color);
965965
}
966966

967-
.docblock .stab, .docblock-short .stab, .docblock p code {
967+
.docblock .stab, .item-table dd .stab, .docblock p code {
968968
display: inline-block;
969969
}
970970

@@ -1069,7 +1069,7 @@ because of the `[-]` element which would overlap with it. */
10691069
.example-wrap .rust a:hover,
10701070
.all-items a:hover,
10711071
.docblock a:not(.scrape-help):not(.tooltip):hover:not(.doc-anchor),
1072-
.docblock-short a:not(.scrape-help):not(.tooltip):hover,
1072+
.item-table dd a:not(.scrape-help):not(.tooltip):hover,
10731073
.item-info a {
10741074
text-decoration: underline;
10751075
}
@@ -1102,20 +1102,17 @@ table,
11021102
}
11031103

11041104
.item-table {
1105-
display: table;
11061105
padding: 0;
11071106
margin: 0;
11081107
width: 100%;
11091108
}
1110-
.item-table > li {
1111-
display: table-row;
1112-
}
1113-
.item-table > li > div {
1114-
display: table-cell;
1115-
}
1116-
.item-table > li > .item-name {
1109+
.item-table > dt {
11171110
padding-right: 1.25rem;
11181111
}
1112+
.item-table > dd {
1113+
margin-inline-start: 0;
1114+
margin-left: 0;
1115+
}
11191116

11201117
.search-results-title {
11211118
margin-top: 0;
@@ -1415,7 +1412,7 @@ so that we can apply CSS-filters to change the arrow color in themes */
14151412
padding: 3px;
14161413
margin-bottom: 5px;
14171414
}
1418-
.item-name .stab {
1415+
.item-table dt .stab {
14191416
margin-left: 0.3125em;
14201417
}
14211418
.stab {
@@ -2476,16 +2473,15 @@ in src-script.js and main.js
24762473
}
24772474

24782475
/* Display an alternating layout on tablets and phones */
2479-
.item-table, .item-row, .item-table > li, .item-table > li > div,
2480-
.search-results > a, .search-results > a > div {
2476+
.item-row, .search-results > a, .search-results > a > div {
24812477
display: block;
24822478
}
24832479

24842480
/* Display an alternating layout on tablets and phones */
24852481
.search-results > a {
24862482
padding: 5px 0px;
24872483
}
2488-
.search-results > a > div.desc, .item-table > li > div.desc {
2484+
.search-results > a > div.desc, .item-table dd {
24892485
padding-left: 2em;
24902486
}
24912487
.search-results .result-name {
@@ -2546,12 +2542,20 @@ in src-script.js and main.js
25462542
box-shadow: 0 0 4px var(--main-background-color);
25472543
}
25482544

2549-
.item-table > li > .item-name {
2550-
width: 33%;
2545+
/* Since the screen is wide enough, we show items on their description on the same line. */
2546+
.item-table:not(.reexports) {
2547+
display: grid;
2548+
grid-template-columns: 33% 67%;
25512549
}
2552-
.item-table > li > div {
2550+
.item-table > dt, .item-table > dd {
25532551
overflow-wrap: anywhere;
25542552
}
2553+
.item-table > dt {
2554+
grid-column-start: 1;
2555+
}
2556+
.item-table > dd {
2557+
grid-column-start: 2;
2558+
}
25552559
}
25562560

25572561
@media print {

‎tests/rustdoc-gui/huge-collection-of-constants.goml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
go-to: "file://" + |DOC_PATH| + "/test_docs/huge_amount_of_consts/index.html"
44

55
compare-elements-position-near-false: (
6-
"//ul[@class='item-table']/li[last()-1]",
7-
"//ul[@class='item-table']/li[last()-3]",
6+
"//dl[@class='item-table']/dt[last()-1]",
7+
"//dl[@class='item-table']/dt[last()-3]",
88
{"y": 12},
99
)

‎tests/rustdoc-gui/item-name-wrap.goml

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,21 +3,21 @@ go-to: "file://" + |DOC_PATH| + "/test_docs/short_docs/index.html"
33
set-window-size: (1000, 600)
44

55
// First we ensure that there is only one `item-table`...
6-
assert-count: ("ul.item-table", 1)
6+
assert-count: ("dl.item-table", 1)
77
// And only two items in it.
8-
assert-count: ("ul.item-table li", 2)
8+
assert-count: ("dl.item-table dt", 2)
99

1010
// If they don't have the same height, then it means one of the two is on two lines whereas it
1111
// shouldn't!
1212
compare-elements-size: (
13-
".item-table .item-name a[href='fn.mult_vec_num.html']",
14-
".item-table .item-name a[href='fn.subt_vec_num.html']",
13+
".item-table dt a[href='fn.mult_vec_num.html']",
14+
".item-table dt a[href='fn.subt_vec_num.html']",
1515
["height"],
1616
)
1717

1818
// We also check that the `item-table` is taking the full width.
1919
compare-elements-size: (
2020
"#functions",
21-
"ul.item-table",
21+
"dl.item-table",
2222
["width"],
2323
)

‎tests/rustdoc-gui/item-summary-table.goml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
// This test ensures that <table> elements aren't display in items summary.
22
go-to: "file://" + |DOC_PATH| + "/lib2/summary_table/index.html"
33
// We check that we picked the right item first.
4-
assert-text: (".item-table .item-name", "Foo")
4+
assert-text: (".item-table dt", "Foo")
55
// Then we check that its summary is empty.
6-
assert-false: ".item-table .desc"
6+
assert-false: ".item-table dd"

‎tests/rustdoc-gui/label-next-to-symbol.goml

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -12,59 +12,59 @@ assert: (".stab.portability")
1212

1313
// make sure that deprecated and portability have the right colors
1414
assert-css: (
15-
".item-table .item-name .stab.deprecated",
15+
".item-table dt .stab.deprecated",
1616
{ "background-color": "#fff5d6" },
1717
)
1818
assert-css: (
19-
".item-table .item-name .stab.portability",
19+
".item-table dt .stab.portability",
2020
{ "background-color": "#fff5d6" },
2121
)
2222

2323
// table like view
24-
assert-css: (".desc.docblock-short", { "padding-left": "0px" })
24+
assert-css: ("dd", { "padding-left": "0px" })
2525
compare-elements-position-near: (
26-
"//*[@class='item-name']//a[normalize-space()='replaced_function']",
27-
".item-name .stab.deprecated",
26+
"//dt//a[normalize-space()='replaced_function']",
27+
"dt .stab.deprecated",
2828
{"y": 2},
2929
)
3030
// "Unix" part is on second line
3131
compare-elements-position-false: (
32-
".item-name .stab.deprecated",
33-
".item-name .stab.portability",
32+
"dt .stab.deprecated",
33+
"dt .stab.portability",
3434
["y"],
3535
)
3636

3737
// Ensure no wrap
3838
compare-elements-position: (
39-
"//*[@class='item-name']//a[normalize-space()='replaced_function']/..",
40-
"//*[@class='desc docblock-short'][normalize-space()='a thing with a label']",
39+
"//dt//a[normalize-space()='replaced_function']/..",
40+
"//dd[normalize-space()='a thing with a label']",
4141
["y"],
4242
)
4343

4444
// Mobile view
4545
set-window-size: (600, 600)
4646
// staggered layout with 2em spacing
47-
assert-css: (".desc.docblock-short", { "padding-left": "32px" })
47+
assert-css: ("dd", { "padding-left": "32px" })
4848
compare-elements-position-near: (
49-
"//*[@class='item-name']//a[normalize-space()='replaced_function']",
50-
".item-name .stab.deprecated",
49+
"//dt//a[normalize-space()='replaced_function']",
50+
"dt .stab.deprecated",
5151
{"y": 2},
5252
)
5353
compare-elements-position: (
54-
".item-name .stab.deprecated",
55-
".item-name .stab.portability",
54+
"dt .stab.deprecated",
55+
"dt .stab.portability",
5656
["y"],
5757
)
5858

5959
// Ensure wrap
6060
compare-elements-position-false: (
61-
"//*[@class='item-name']//a[normalize-space()='replaced_function']/..",
62-
"//*[@class='desc docblock-short'][normalize-space()='a thing with a label']",
61+
"//dt//a[normalize-space()='replaced_function']/..",
62+
"//dd[normalize-space()='a thing with a label']",
6363
["y"],
6464
)
6565
compare-elements-position-false: (
66-
".item-name .stab.deprecated",
67-
"//*[@class='desc docblock-short'][normalize-space()='a thing with a label']",
66+
"dt .stab.deprecated",
67+
"//dd[normalize-space()='a thing with a label']",
6868
["y"],
6969
)
7070

0 commit comments

Comments
 (0)