user0/rust
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Auto merge of #85651 - dns2utf8:rustdoc_flexbox, r=GuillaumeGomez

Browse source 
rustdoc: staggered layout for module contents on mobile

This PR adds the container `<item-table>` with its two children `<item-left>` and `<item-right>`.
It uses grid-layout on desktop and flexbox on mobile to make better use of the available space.

Additionally it allows to share parts of the CSS with the search function.

* Demo: https://data.estada.ch/rustdoc-nightly_126561cb3_2021-05-25/generic_array/index.html
* Related: #85540

## Desktop
![grafik](https://user-images.githubusercontent.com/739070/119416896-2be62300-bce4-11eb-9555-792b859ab611.png)

## Mobile
![grafik](https://user-images.githubusercontent.com/739070/119416934-44563d80-bce4-11eb-9e77-70a72edcc487.png)

r? `@GuillaumeGomez` `@jsha`
This commit is contained in:
bors 2021-06-24 20:01:39 +00:00
commit 7c3872e6bf
16 changed files with 129 additions and 76 deletions
Download patch file Download diff file Expand all files Collapse all files

1
src/librustdoc/html/render/mod.rs
View file

@ -1694,6 +1694,7 @@ fn print_sidebar(cx: &Context<'_>, it: &clean::Item, buffer: &mut Buffer) {
write!(
buffer,
"<div class=\"block version\">\
<div class=\"narrow-helper\"></div>\
<p>Version {}</p>\
</div>",
Escape(version),

34
src/librustdoc/html/render/print_item.rs
View file

@ -29,6 +29,9 @@ use crate::html::highlight;
use crate::html::layout::Page;
use crate::html::markdown::MarkdownSummaryLine;
const ITEM_TABLE_OPEN: &'static str = "<div class=\"item-table\">";
const ITEM_TABLE_CLOSE: &'static str = "</div>";
pub(super) fn print_item(cx: &Context<'_>, item: &clean::Item, buf: &mut Buffer, page: &Page<'_>) {
debug_assert!(!item.is_stripped());
// Write the breadcrumb trail header for the top
@ -263,14 +266,15 @@ fn item_module(w: &mut Buffer, cx: &Context<'_>, item: &clean::Item, items: &[cl
curty = myty;
} else if myty != curty {
if curty.is_some() {
w.write_str("</table>");
w.write_str(ITEM_TABLE_CLOSE);
}
curty = myty;
let (short, name) = item_ty_to_strs(myty.unwrap());
write!(
w,
"<h2 id=\"{id}\" class=\"section-header\">\
<a href=\"#{id}\">{name}</a></h2>\n<table>",
<a href=\"#{id}\">{name}</a></h2>\n{}",
ITEM_TABLE_OPEN,
id = cx.derive_id(short.to_owned()),
name = name
);
@ -283,14 +287,14 @@ fn item_module(w: &mut Buffer, cx: &Context<'_>, item: &clean::Item, items: &[cl
match *src {
Some(ref src) => write!(
w,
"<tr><td><code>{}extern crate {} as {};",
"<div class=\"item-left\"><code>{}extern crate {} as {};",
myitem.visibility.print_with_space(myitem.def_id, cx),
anchor(myitem.def_id.expect_real(), &*src.as_str(), cx),
myitem.name.as_ref().unwrap(),
),
None => write!(
w,
"<tr><td><code>{}extern crate {};",
"<div class=\"item-left\"><code>{}extern crate {};",
myitem.visibility.print_with_space(myitem.def_id, cx),
anchor(
myitem.def_id.expect_real(),
@ -299,7 +303,7 @@ fn item_module(w: &mut Buffer, cx: &Context<'_>, item: &clean::Item, items: &[cl
),
),
}
w.write_str("</code></td></tr>");
w.write_str("</code></div>");
}
clean::ImportItem(ref import) => {
@ -326,10 +330,10 @@ fn item_module(w: &mut Buffer, cx: &Context<'_>, item: &clean::Item, items: &[cl
write!(
w,
"<tr class=\"{stab}{add}import-item\">\
<td><code>{vis}{imp}</code></td>\
<td class=\"docblock-short\">{stab_tags}</td>\
</tr>",
"<div class=\"item-left {stab}{add}import-item\">\
<code>{vis}{imp}</code>\
</div>\
<div class=\"item-right docblock-short\">{stab_tags}</div>",
stab = stab.unwrap_or_default(),
add = add,
vis = myitem.visibility.print_with_space(myitem.def_id, cx),
@ -358,11 +362,11 @@ fn item_module(w: &mut Buffer, cx: &Context<'_>, item: &clean::Item, items: &[cl
let doc_value = myitem.doc_value().unwrap_or_default();
write!(
w,
"<tr class=\"{stab}{add}module-item\">\
<td><a class=\"{class}\" href=\"{href}\" \
title=\"{title}\">{name}</a>{unsafety_flag}</td>\
<td class=\"docblock-short\">{stab_tags}{docs}</td>\
</tr>",
"<div class=\"item-left {stab}{add}module-item\">\
<a class=\"{class}\" href=\"{href}\" \
title=\"{title}\">{name}</a>{unsafety_flag}\
</div>\
<div class=\"item-right docblock-short\">{stab_tags}{docs}</div>",
name = *myitem.name.as_ref().unwrap(),
stab_tags = extra_info_tags(myitem, item, cx.tcx()),
docs = MarkdownSummaryLine(&doc_value, &myitem.links(cx)).into_string(),
@ -382,7 +386,7 @@ fn item_module(w: &mut Buffer, cx: &Context<'_>, item: &clean::Item, items: &[cl
}
if curty.is_some() {
w.write_str("</table>");
w.write_str(ITEM_TABLE_CLOSE);
}
}

50
src/librustdoc/html/static/rustdoc.css
View file

@ -169,6 +169,7 @@ div.impl-items > div {
h1, h2, h3, h4,
.sidebar, a.source, .search-input, .search-results .result-name,
.content table td:first-child > a,
.item-left > a,
div.item-list .out-of-band, span.since,
#source-sidebar, #sidebar-toggle,
details.rustdoc-toggle > summary::before,
@ -710,6 +711,25 @@ a {
.block a.current.crate { font-weight: 500; }
.item-table {
display: grid;
column-gap: 1.2rem;
row-gap: 0.0rem;
grid-template-columns: auto 1fr;
/* align content left */
justify-items: start;
}
.item-left, .item-right {
display: block;
}
.item-left {
grid-column: 1;
}
.item-right {
grid-column: 2;
}
.search-container {
position: relative;
}
@ -1599,9 +1619,25 @@ details.undocumented[open] > summary::before {
}
.sidebar > .block.version {
overflow: hidden;
border-bottom: none;
margin-top: 12px;
margin-bottom: 0;
height: 100%;
padding-left: 12px;
}
.sidebar > .block.version > div.narrow-helper {
float: left;
width: 1px;
height: 100%;
}
.sidebar > .block.version > p {
/* hide Version text if too narrow */
margin: 0;
min-width: 55px;
/* vertically center */
display: flex;
align-items: center;
height: 100%;
}
nav.sub {
@ -1737,6 +1773,16 @@ details.undocumented[open] > summary::before {
#help-button {
display: none;
}
/* Display an alternating layout on tablets and phones */
.item-table {
display: flex;
flex-flow: column wrap;
}
.item-left, .item-right {
width: 100%;
}
.search-container > div {
width: calc(100% - 32px);
}
@ -1749,7 +1795,7 @@ details.undocumented[open] > summary::before {
.search-results .result-name, .search-results div.desc, .search-results .result-description {
width: 100%;
}
.search-results div.desc, .search-results .result-description {
.search-results div.desc, .search-results .result-description, .item-right {
padding-left: 2em;
}
}

10
src/test/rustdoc-gui/sidebar.goml
View file

@ -13,8 +13,8 @@ assert-text: (".sidebar-elems > .items > ul > li:nth-child(4)", "Traits")
assert-text: (".sidebar-elems > .items > ul > li:nth-child(5)", "Functions")
assert-text: (".sidebar-elems > .items > ul > li:nth-child(6)", "Type Definitions")
assert-text: (".sidebar-elems > .items > ul > li:nth-child(7)", "Keywords")
assert-text: ("#structs + table td > a", "Foo")
click: "#structs + table td > a"
assert-text: ("#structs + .item-table .item-left > a", "Foo")
click: "#structs + .item-table .item-left > a"
// PAGE: struct.Foo.html
assert-count: (".sidebar .location", 2)
@ -35,8 +35,8 @@ assert-text: (".sidebar-elems > .items > ul > li:nth-child(2)", "Structs")
assert-text: (".sidebar-elems > .items > ul > li:nth-child(3)", "Traits")
assert-text: (".sidebar-elems > .items > ul > li:nth-child(4)", "Functions")
assert-text: (".sidebar-elems > .items > ul > li:nth-child(5)", "Type Definitions")
assert-text: ("#functions + table td > a", "foobar")
click: "#functions + table td > a"
assert-text: ("#functions + .item-table .item-left > a", "foobar")
click: "#functions + .item-table .item-left > a"
// PAGE: fn.foobar.html
// In items containing no items (like functions or constants) and in modules, we have one
@ -57,4 +57,4 @@ assert-text: (".sidebar > .location", "Module sub_sub_module")
// We check that we don't have the crate list.
assert-false: ".sidebar-elems > .crate"
assert-text: (".sidebar-elems > .items > ul > li:nth-child(1)", "Functions")
assert-text: ("#functions + table td > a", "foo")
assert-text: ("#functions + .item-table .item-left > a", "foo")

6
src/test/rustdoc/deprecated.rs
View file

@ -1,6 +1,6 @@
// @has deprecated/index.html '//*[@class="docblock-short"]/span[@class="stab deprecated"]' \
// @has deprecated/index.html '//*[@class="item-right docblock-short"]/span[@class="stab deprecated"]' \
// 'Deprecated'
// @has - '//*[@class="docblock-short"]' 'Deprecated docs'
// @has - '//*[@class="item-right docblock-short"]' 'Deprecated docs'
// @has deprecated/struct.S.html '//*[@class="stab deprecated"]' \
// 'Deprecated since 1.0.0: text'
@ -8,7 +8,7 @@
#[deprecated(since = "1.0.0", note = "text")]
pub struct S;
// @matches deprecated/index.html '//*[@class="docblock-short"]' '^Docs'
// @matches deprecated/index.html '//*[@class="item-right docblock-short"]' '^Docs'
/// Docs
pub struct T;

6
src/test/rustdoc/doc-cfg.rs
View file

@ -12,7 +12,7 @@ pub struct Portable;
// @has doc_cfg/unix_only/index.html \
// '//*[@id="main"]/*[@class="item-info"]/*[@class="stab portability"]' \
// 'This is supported on Unix only.'
// @matches - '//*[@class="module-item"]//*[@class="stab portability"]' '\AARM\Z'
// @matches - '//*[@class="item-right docblock-short"]//*[@class="stab portability"]' '\AARM\Z'
// @count - '//*[@class="stab portability"]' 2
#[doc(cfg(unix))]
pub mod unix_only {
@ -42,7 +42,7 @@ pub mod unix_only {
// @has doc_cfg/wasi_only/index.html \
// '//*[@id="main"]/*[@class="item-info"]/*[@class="stab portability"]' \
// 'This is supported on WASI only.'
// @matches - '//*[@class="module-item"]//*[@class="stab portability"]' '\AWebAssembly\Z'
// @matches - '//*[@class="item-right docblock-short"]//*[@class="stab portability"]' '\AWebAssembly\Z'
// @count - '//*[@class="stab portability"]' 2
#[doc(cfg(target_os = "wasi"))]
pub mod wasi_only {
@ -74,7 +74,7 @@ pub mod wasi_only {
// the portability header is different on the module view versus the full view
// @has doc_cfg/index.html
// @matches - '//*[@class="module-item"]//*[@class="stab portability"]' '\Aavx\Z'
// @matches - '//*[@class="item-right docblock-short"]//*[@class="stab portability"]' '\Aavx\Z'
// @has doc_cfg/fn.uses_target_feature.html
// @has - '//*[@id="main"]/*[@class="item-info"]/*[@class="stab portability"]' \

4
src/test/rustdoc/duplicate-cfg.rs
View file

@ -2,8 +2,8 @@
#![feature(doc_cfg)]
// @has 'foo/index.html'
// @matches '-' '//*[@class="module-item"]//*[@class="stab portability"]' '^sync$'
// @has '-' '//*[@class="module-item"]//*[@class="stab portability"]/@title' 'This is supported on crate feature `sync` only'
// @matches '-' '//*[@class="item-right docblock-short"]//*[@class="stab portability"]' '^sync$'
// @has '-' '//*[@class="item-right docblock-short"]//*[@class="stab portability"]/@title' 'This is supported on crate feature `sync` only'
// @has 'foo/struct.Foo.html'
// @has '-' '//*[@class="stab portability"]' 'sync'

4
src/test/rustdoc/inline_cross/macros.rs
View file

@ -7,8 +7,8 @@
extern crate macros;
// @has foo/index.html '//*[@class="docblock-short"]/span[@class="stab deprecated"]' Deprecated
// @has - '//*[@class="docblock-short"]/span[@class="stab unstable"]' Experimental
// @has foo/index.html '//*[@class="item-right docblock-short"]/span[@class="stab deprecated"]' Deprecated
// @has - '//*[@class="item-right docblock-short"]/span[@class="stab unstable"]' Experimental
// @has foo/macro.my_macro.html
// @has - '//*[@class="docblock"]' 'docs for my_macro'

8
src/test/rustdoc/internal.rs
View file

@ -2,9 +2,11 @@
// Check that the unstable marker is not added for "rustc_private".
// @!matches internal/index.html '//*[@class="docblock-short"]/span[@class="stab unstable"]'
// @!matches internal/index.html '//*[@class="docblock-short"]/span[@class="stab internal"]'
// @matches - '//*[@class="docblock-short"]' 'Docs'
// @!matches internal/index.html \
// '//*[@class="item-right docblock-short"]/span[@class="stab unstable"]'
// @!matches internal/index.html \
// '//*[@class="item-right docblock-short"]/span[@class="stab internal"]'
// @matches - '//*[@class="item-right docblock-short"]' 'Docs'
// @!has internal/struct.S.html '//*[@class="stab unstable"]'
// @!has internal/struct.S.html '//*[@class="stab internal"]'

10
src/test/rustdoc/issue-32374.rs
View file

@ -1,17 +1,17 @@
#![feature(staged_api)]
#![doc(issue_tracker_base_url = "http://issue_url/")]
#![doc(issue_tracker_base_url = "https://issue_url/")]
#![unstable(feature="test", issue = "32374")]
// @matches issue_32374/index.html '//*[@class="docblock-short"]/span[@class="stab deprecated"]' \
// @matches issue_32374/index.html '//*[@class="item-right docblock-short"]/span[@class="stab deprecated"]' \
// 'Deprecated'
// @matches issue_32374/index.html '//*[@class="docblock-short"]/span[@class="stab unstable"]' \
// @matches issue_32374/index.html '//*[@class="item-right docblock-short"]/span[@class="stab unstable"]' \
// 'Experimental'
// @matches issue_32374/index.html '//*[@class="docblock-short"]/text()' 'Docs'
// @matches issue_32374/index.html '//*[@class="item-right docblock-short"]/text()' 'Docs'
// @has issue_32374/struct.T.html '//*[@class="stab deprecated"]' \
// '👎 Deprecated since 1.0.0: text'
// @has - '<code>test</code>&nbsp;<a href="http://issue_url/32374">#32374</a>'
// @has - '<code>test</code>&nbsp;<a href="https://issue_url/32374">#32374</a>'
// @matches issue_32374/struct.T.html '//*[@class="stab unstable"]' \
// '🔬 This is a nightly-only experimental API. \(test\s#32374\)$'
/// Docs

2
src/test/rustdoc/issue-46377.rs
View file

@ -1,3 +1,3 @@
// @has 'issue_46377/index.html' '//*[@class="docblock-short"]' 'Check out this struct!'
// @has 'issue_46377/index.html' '//*[@class="item-right docblock-short"]' 'Check out this struct!'
/// # Check out this struct!
pub struct SomeStruct;

8
src/test/rustdoc/issue-55364.rs
View file

@ -29,8 +29,8 @@ pub mod subone {
// @has - '//section[@id="main"]/details/div[@class="docblock"]//a[@href="../fn.foo.html"]' 'foo'
// @has - '//section[@id="main"]/details/div[@class="docblock"]//a[@href="../fn.bar.html"]' 'bar'
// Though there should be such links later
// @has - '//section[@id="main"]/table//tr[@class="module-item"]/td/a[@class="fn"][@href="fn.foo.html"]' 'foo'
// @has - '//section[@id="main"]/table//tr[@class="module-item"]/td/a[@class="fn"][@href="fn.bar.html"]' 'bar'
// @has - '//section[@id="main"]/div[@class="item-table"]//div[@class="item-left module-item"]/a[@class="fn"][@href="fn.foo.html"]' 'foo'
// @has - '//section[@id="main"]/div[@class="item-table"]//div[@class="item-left module-item"]/a[@class="fn"][@href="fn.bar.html"]' 'bar'
/// See either [foo] or [bar].
pub mod subtwo {
@ -68,8 +68,8 @@ pub mod subthree {
// Next we go *deeper* - In order to ensure it's not just "this or parent"
// we test `crate::` and a `super::super::...` chain
// @has issue_55364/subfour/subfive/subsix/subseven/subeight/index.html
// @has - '//section[@id="main"]/table//tr[@class="module-item"]/td[@class="docblock-short"]//a[@href="../../../../../subone/fn.foo.html"]' 'other foo'
// @has - '//section[@id="main"]/table//tr[@class="module-item"]/td[@class="docblock-short"]//a[@href="../../../../../subtwo/fn.bar.html"]' 'other bar'
// @has - '//section[@id="main"]/div[@class="item-table"]//div[@class="item-right docblock-short"]//a[@href="../../../../../subone/fn.foo.html"]' 'other foo'
// @has - '//section[@id="main"]/div[@class="item-table"]//div[@class="item-right docblock-short"]//a[@href="../../../../../subtwo/fn.bar.html"]' 'other bar'
pub mod subfour {
pub mod subfive {
pub mod subsix {

6
src/test/rustdoc/reexport-check.rs
View file

@ -4,15 +4,15 @@
extern crate reexport_check;
// @!has 'foo/index.html' '//code' 'pub use self::i32;'
// @has 'foo/index.html' '//tr[@class="deprecated module-item"]' 'i32'
// @has 'foo/index.html' '//div[@class="item-left deprecated module-item"]' 'i32'
// @has 'foo/i32/index.html'
#[allow(deprecated, deprecated_in_future)]
pub use std::i32;
// @!has 'foo/index.html' '//code' 'pub use self::string::String;'
// @has 'foo/index.html' '//tr[@class="module-item"]' 'String'
// @has 'foo/index.html' '//div[@class="item-left module-item"]' 'String'
pub use std::string::String;
// @has 'foo/index.html' '//td[@class="docblock-short"]' 'Docs in original'
// @has 'foo/index.html' '//div[@class="item-right docblock-short"]' 'Docs in original'
// this is a no-op, but shows what happens if there's an attribute that isn't a doc-comment
#[doc(inline)]
pub use reexport_check::S;

6
src/test/rustdoc/short-docblock-codeblock.rs
View file

@ -1,8 +1,8 @@
#![crate_name = "foo"]
// @has foo/index.html '//*[@class="module-item"]//td[@class="docblock-short"]' ""
// @!has foo/index.html '//*[@id="module-item"]//td[@class="docblock-short"]' "Some text."
// @!has foo/index.html '//*[@id="module-item"]//td[@class="docblock-short"]' "let x = 12;"
// @has foo/index.html '//*[@class="item-right docblock-short"]' ""
// @!has foo/index.html '//*[@class="item-right docblock-short"]' "Some text."
// @!has foo/index.html '//*[@class="item-right docblock-short"]' "let x = 12;"
/// ```
/// let x = 12;

25
src/test/rustdoc/short-docblock.rs Normal file
View file

@ -0,0 +1,25 @@
#![crate_name = "foo"]
// @has foo/index.html '//*[@class="item-right docblock-short"]/p' 'fooo'
// @!has foo/index.html '//*[@class="item-right docblock-short"]/p/h1' 'fooo'
// @has foo/fn.foo.html '//h1[@id="fooo"]/a[@href="#fooo"]' 'fooo'
/// # fooo
///
/// foo
pub fn foo() {}
// @has foo/index.html '//*[@class="item-right docblock-short"]/p' 'mooood'
// @!has foo/index.html '//*[@class="item-right docblock-short"]/p/h2' 'mooood'
// @has foo/foo/index.html '//h2[@id="mooood"]/a[@href="#mooood"]' 'mooood'
/// ## mooood
///
/// foo mod
pub mod foo {}
// @has foo/index.html '//*[@class="item-right docblock-short"]/p/a[@href=\
// "https://nougat.world"]/code' 'nougat'
/// [`nougat`](https://nougat.world)
pub struct Bar;

25
src/test/rustdoc/short-dockblock.rs
View file

@ -1,25 +0,0 @@
#![crate_name = "foo"]
// @has foo/index.html '//*[@class="docblock-short"]/p' 'fooo'
// @!has foo/index.html '//*[@class="docblock-short"]/p/h1' 'fooo'
// @has foo/fn.foo.html '//h1[@id="fooo"]/a[@href="#fooo"]' 'fooo'
/// # fooo
///
/// foo
pub fn foo() {}
// @has foo/index.html '//*[@class="docblock-short"]/p' 'mooood'
// @!has foo/index.html '//*[@class="docblock-short"]/p/h2' 'mooood'
// @has foo/foo/index.html '//h2[@id="mooood"]/a[@href="#mooood"]' 'mooood'
/// ## mooood
///
/// foo mod
pub mod foo {}
// @has foo/index.html '//*[@class="docblock-short"]/p/a[@href=\
// "https://nougat.world"]/code' 'nougat'
/// [`nougat`](https://nougat.world)
pub struct Bar;