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

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`
rust-lang · Jun 24, 2021 · 7c3872e · 7c3872e
2 parents cbeda5c + 94c84bd
commit 7c3872e
Show file tree

Hide file tree

Showing 16 changed files with 129 additions and 76 deletions.
diff --git a/src/librustdoc/html/render/mod.rs b/src/librustdoc/html/render/mod.rs
@@ -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),

diff --git a/src/librustdoc/html/render/print_item.rs b/src/librustdoc/html/render/print_item.rs
@@ -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);
     }
 }
 

diff --git a/src/librustdoc/html/static/rustdoc.css b/src/librustdoc/html/static/rustdoc.css
@@ -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;
 	}
 }

diff --git a/src/test/rustdoc-gui/sidebar.goml b/src/test/rustdoc-gui/sidebar.goml
@@ -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")
diff --git a/src/test/rustdoc/deprecated.rs b/src/test/rustdoc/deprecated.rs
@@ -1,14 +1,14 @@
-// @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'
 /// Deprecated docs
 #[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;
 

diff --git a/src/test/rustdoc/doc-cfg.rs b/src/test/rustdoc/doc-cfg.rs
@@ -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"]' \

diff --git a/src/test/rustdoc/duplicate-cfg.rs b/src/test/rustdoc/duplicate-cfg.rs
@@ -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'

diff --git a/src/test/rustdoc/inline_cross/macros.rs b/src/test/rustdoc/inline_cross/macros.rs
@@ -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'

diff --git a/src/test/rustdoc/internal.rs b/src/test/rustdoc/internal.rs
@@ -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"]'

diff --git a/src/test/rustdoc/issue-32374.rs b/src/test/rustdoc/issue-32374.rs
@@ -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

diff --git a/src/test/rustdoc/issue-46377.rs b/src/test/rustdoc/issue-46377.rs
@@ -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;
diff --git a/src/test/rustdoc/issue-55364.rs b/src/test/rustdoc/issue-55364.rs
@@ -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 {

diff --git a/src/test/rustdoc/reexport-check.rs b/src/test/rustdoc/reexport-check.rs
@@ -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;
diff --git a/src/test/rustdoc/short-docblock-codeblock.rs b/src/test/rustdoc/short-docblock-codeblock.rs
@@ -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;