Skip to content

Commit

Permalink
Unrolled build for rust-lang#135641
Browse files Browse the repository at this point in the history 
Rollup merge of rust-lang#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`
  • Loading branch information
@rust-timer
rust-timer authored Jan 19, 2025
2 parents 01706e1 + b3865d1 commit 246fe18
Show file tree
Hide file tree
Showing 47 changed files with 185 additions and 221 deletions.
53 changes: 17 additions & 36 deletions src/librustdoc/html/render/print_item.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -140,10 +140,9 @@ macro_rules! item_template_methods {
};
}

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

// A component in a `use` path, like `string` in std::string::ToString
struct PathComponent {
Expand Down Expand Up @@ -400,66 +399,53 @@ fn item_module(w: &mut Buffer, cx: &Context<'_>, item: &clean::Item, items: &[cl
w.write_str(ITEM_TABLE_CLOSE);
}
last_section = Some(my_section);
write_section_heading(
w,
my_section.name(),
&cx.derive_id(my_section.id()),
None,
ITEM_TABLE_OPEN,
);
let section_id = my_section.id();
let tag =
if section_id == "reexports" { REEXPORTS_TABLE_OPEN } else { ITEM_TABLE_OPEN };
write_section_heading(w, my_section.name(), &cx.derive_id(section_id), None, tag);
}

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

w.write_str(ITEM_TABLE_ROW_OPEN);
match *src {
Some(src) => write!(
w,
"<div class=\"item-name\"><code>{}extern crate {} as {};",
"<dt><code>{}extern crate {} as {};",
visibility_print_with_space(myitem, cx),
anchor(myitem.item_id.expect_def_id(), src, cx),
EscapeBodyTextWithWbr(myitem.name.unwrap().as_str()),
),
None => write!(
w,
"<div class=\"item-name\"><code>{}extern crate {};",
"<dt><code>{}extern crate {};",
visibility_print_with_space(myitem, cx),
anchor(myitem.item_id.expect_def_id(), myitem.name.unwrap(), cx),
),
}
w.write_str("</code></div>");
w.write_str(ITEM_TABLE_ROW_CLOSE);
w.write_str("</code></dt>");
}

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

w.write_str(ITEM_TABLE_ROW_OPEN);
let id = match import.kind {
clean::ImportKind::Simple(s) => {
format!(" id=\"{}\"", cx.derive_id(format!("reexport.{s}")))
}
clean::ImportKind::Glob => String::new(),
};
let (stab_tags_before, stab_tags_after) = if stab_tags.is_empty() {
("", "")
} else {
("<div class=\"desc docblock-short\">", "</div>")
};
write!(
w,
"<div class=\"item-name\"{id}>\
<code>{vis}{imp}</code>\
</div>\
{stab_tags_before}{stab_tags}{stab_tags_after}",
"<dt{id}>\
<code>{vis}{imp}</code>{stab_tags}\
</dt>",
vis = visibility_print_with_space(myitem, cx),
imp = import.print(cx),
);
w.write_str(ITEM_TABLE_ROW_CLOSE);
}

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

w.write_str(ITEM_TABLE_ROW_OPEN);
let docs =
MarkdownSummaryLine(&myitem.doc_value(), &myitem.links(cx)).into_string();
let (docs_before, docs_after) = if docs.is_empty() {
("", "")
} else {
("<div class=\"desc docblock-short\">", "</div>")
};
let (docs_before, docs_after) =
if docs.is_empty() { ("", "") } else { ("<dd>", "</dd>") };
write!(
w,
"<div class=\"item-name\">\
"<dt>\
<a class=\"{class}\" href=\"{href}\" title=\"{title}\">{name}</a>\
{visibility_and_hidden}\
{unsafety_flag}\
{stab_tags}\
</div>\
</dt>\
{docs_before}{docs}{docs_after}",
name = EscapeBodyTextWithWbr(myitem.name.unwrap().as_str()),
visibility_and_hidden = visibility_and_hidden,
Expand All @@ -521,7 +503,6 @@ fn item_module(w: &mut Buffer, cx: &Context<'_>, item: &clean::Item, items: &[cl
.collect::<Vec<_>>()
.join(" "),
);
w.write_str(ITEM_TABLE_ROW_CLOSE);
}
}
}
Expand Down
50 changes: 27 additions & 23 deletions src/librustdoc/html/static/css/rustdoc.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -242,7 +242,7 @@ h1, h2, h3, h4, h5, h6,
.mobile-topbar,
.search-input,
.search-results .result-name,
.item-name > a,
.item-table dt > a,
.out-of-band,
.sub-heading,
span.since,
Expand Down Expand Up @@ -385,11 +385,11 @@ details:not(.toggle) summary {
code, pre, .code-header, .type-signature {
font-family: "Source Code Pro", monospace;
}
.docblock code, .docblock-short code {
.docblock code, .item-table dd code {
border-radius: 3px;
padding: 0 0.125em;
}
.docblock pre code, .docblock-short pre code {
.docblock pre code, .item-table dd pre code {
padding: 0;
}
pre {
Expand Down Expand Up @@ -887,13 +887,13 @@ both the code example and the line numbers, so we need to remove the radius in t
text-align: center;
}

.docblock-short {
.item-table dd {
overflow-wrap: break-word;
overflow-wrap: anywhere;
}
/* Wrap non-pre code blocks (`text`) but not (```text```). */
.docblock :not(pre) > code,
.docblock-short code {
.item-table dd code {
white-space: pre-wrap;
}

Expand Down Expand Up @@ -938,7 +938,7 @@ rustdoc-toolbar {
min-height: 60px;
}

.docblock code, .docblock-short code,
.docblock code, .item-table dd code,
pre, .rustdoc.src .example-wrap, .example-wrap .src-line-numbers {
background-color: var(--code-block-background-color);
border-radius: var(--code-block-border-radius);
Expand All @@ -964,7 +964,7 @@ pre, .rustdoc.src .example-wrap, .example-wrap .src-line-numbers {
background: var(--table-alt-row-background-color);
}

.docblock .stab, .docblock-short .stab, .docblock p code {
.docblock .stab, .item-table dd .stab, .docblock p code {
display: inline-block;
}

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

.item-table {
display: table;
padding: 0;
margin: 0;
width: 100%;
}
.item-table > li {
display: table-row;
}
.item-table > li > div {
display: table-cell;
}
.item-table > li > .item-name {
.item-table > dt {
padding-right: 1.25rem;
}
.item-table > dd {
margin-inline-start: 0;
margin-left: 0;
}

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

/* Display an alternating layout on tablets and phones */
.item-table, .item-row, .item-table > li, .item-table > li > div,
.search-results > a, .search-results > a > div {
.item-row, .search-results > a, .search-results > a > div {
display: block;
}

/* Display an alternating layout on tablets and phones */
.search-results > a {
padding: 5px 0px;
}
.search-results > a > div.desc, .item-table > li > div.desc {
.search-results > a > div.desc, .item-table dd {
padding-left: 2em;
}
.search-results .result-name {
Expand Down Expand Up @@ -2546,12 +2542,20 @@ in src-script.js and main.js
box-shadow: 0 0 4px var(--main-background-color);
}

.item-table > li > .item-name {
width: 33%;
/* Since the screen is wide enough, we show items on their description on the same line. */
.item-table:not(.reexports) {
display: grid;
grid-template-columns: 33% 67%;
}
.item-table > li > div {
.item-table > dt, .item-table > dd {
overflow-wrap: anywhere;
}
.item-table > dt {
grid-column-start: 1;
}
.item-table > dd {
grid-column-start: 2;
}
}

@media print {
Expand Down
4 changes: 2 additions & 2 deletions tests/rustdoc-gui/huge-collection-of-constants.goml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
go-to: "file://" + |DOC_PATH| + "/test_docs/huge_amount_of_consts/index.html"

compare-elements-position-near-false: (
"//ul[@class='item-table']/li[last()-1]",
"//ul[@class='item-table']/li[last()-3]",
"//dl[@class='item-table']/dt[last()-1]",
"//dl[@class='item-table']/dt[last()-3]",
{"y": 12},
)
10 changes: 5 additions & 5 deletions tests/rustdoc-gui/item-name-wrap.goml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,21 +3,21 @@ go-to: "file://" + |DOC_PATH| + "/test_docs/short_docs/index.html"
set-window-size: (1000, 600)

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

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

// We also check that the `item-table` is taking the full width.
compare-elements-size: (
"#functions",
"ul.item-table",
"dl.item-table",
["width"],
)
4 changes: 2 additions & 2 deletions tests/rustdoc-gui/item-summary-table.goml
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
// This test ensures that <table> elements aren't display in items summary.
go-to: "file://" + |DOC_PATH| + "/lib2/summary_table/index.html"
// We check that we picked the right item first.
assert-text: (".item-table .item-name", "Foo")
assert-text: (".item-table dt", "Foo")
// Then we check that its summary is empty.
assert-false: ".item-table .desc"
assert-false: ".item-table dd"
36 changes: 18 additions & 18 deletions tests/rustdoc-gui/label-next-to-symbol.goml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,59 +12,59 @@ assert: (".stab.portability")

// make sure that deprecated and portability have the right colors
assert-css: (
".item-table .item-name .stab.deprecated",
".item-table dt .stab.deprecated",
{ "background-color": "#fff5d6" },
)
assert-css: (
".item-table .item-name .stab.portability",
".item-table dt .stab.portability",
{ "background-color": "#fff5d6" },
)

// table like view
assert-css: (".desc.docblock-short", { "padding-left": "0px" })
assert-css: ("dd", { "padding-left": "0px" })
compare-elements-position-near: (
"//*[@class='item-name']//a[normalize-space()='replaced_function']",
".item-name .stab.deprecated",
"//dt//a[normalize-space()='replaced_function']",
"dt .stab.deprecated",
{"y": 2},
)
// "Unix" part is on second line
compare-elements-position-false: (
".item-name .stab.deprecated",
".item-name .stab.portability",
"dt .stab.deprecated",
"dt .stab.portability",
["y"],
)

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

// Mobile view
set-window-size: (600, 600)
// staggered layout with 2em spacing
assert-css: (".desc.docblock-short", { "padding-left": "32px" })
assert-css: ("dd", { "padding-left": "32px" })
compare-elements-position-near: (
"//*[@class='item-name']//a[normalize-space()='replaced_function']",
".item-name .stab.deprecated",
"//dt//a[normalize-space()='replaced_function']",
"dt .stab.deprecated",
{"y": 2},
)
compare-elements-position: (
".item-name .stab.deprecated",
".item-name .stab.portability",
"dt .stab.deprecated",
"dt .stab.portability",
["y"],
)

// Ensure wrap
compare-elements-position-false: (
"//*[@class='item-name']//a[normalize-space()='replaced_function']/..",
"//*[@class='desc docblock-short'][normalize-space()='a thing with a label']",
"//dt//a[normalize-space()='replaced_function']/..",
"//dd[normalize-space()='a thing with a label']",
["y"],
)
compare-elements-position-false: (
".item-name .stab.deprecated",
"//*[@class='desc docblock-short'][normalize-space()='a thing with a label']",
"dt .stab.deprecated",
"//dd[normalize-space()='a thing with a label']",
["y"],
)

Expand Down
Loading

0 comments on commit 246fe18

Please sign in to comment.