From dc1c39b10ed4650de784e860e2778c3e246f585e Mon Sep 17 00:00:00 2001 From: Andy Russell Date: Thu, 9 Dec 2021 00:21:36 -0500 Subject: rustdoc: decouple stability and const-stability --- src/librustdoc/html/render/mod.rs | 91 +++++++++++++++++++++++---------------- 1 file changed, 55 insertions(+), 36 deletions(-) (limited to 'src/librustdoc/html') diff --git a/src/librustdoc/html/render/mod.rs b/src/librustdoc/html/render/mod.rs index dda74904931..3dfe03b54e9 100644 --- a/src/librustdoc/html/render/mod.rs +++ b/src/librustdoc/html/render/mod.rs @@ -792,6 +792,20 @@ fn assoc_type( } } +/// Writes a span containing the versions at which an item became stable and/or const-stable. For +/// example, if the item became stable at 1.0.0, and const-stable at 1.45.0, this function would +/// write a span containing "1.0.0 (const: 1.45.0)". +/// +/// Returns `true` if a stability annotation was rendered. +/// +/// Stability and const-stability are considered separately. If the item is unstable, no version +/// will be written. If the item is const-unstable, "const: unstable" will be appended to the +/// span, with a link to the tracking issue if present. If an item's stability or const-stability +/// version matches the version of its enclosing item, that version will be omitted. +/// +/// Note that it is possible for an unstable function to be const-stable. In that case, the span +/// will include the const-stable version, but no stable version will be emitted, as a natural +/// consequence of the above rules. fn render_stability_since_raw( w: &mut Buffer, ver: Option, @@ -799,51 +813,56 @@ fn render_stability_since_raw( containing_ver: Option, containing_const_ver: Option, ) -> bool { - let ver = ver.filter(|inner| !inner.is_empty()); + let stable_version = ver.filter(|inner| !inner.is_empty() && Some(*inner) != containing_ver); - match (ver, const_stability) { - // stable and const stable - (Some(v), Some(ConstStability { level: StabilityLevel::Stable { since }, .. })) + let mut title = String::new(); + let mut stability = String::new(); + + if let Some(ver) = stable_version { + stability.push_str(&ver.as_str()); + title.push_str(&format!("Stable since Rust version {}", ver)); + } + + let const_title_and_stability = match const_stability { + Some(ConstStability { level: StabilityLevel::Stable { since }, .. }) if Some(since) != containing_const_ver => { - write!( - w, - "{0} (const: {1})", - v, since - ); + Some((format!("const since {}", since), format!("const: {}", since))) } - // stable and const unstable - ( - Some(v), - Some(ConstStability { level: StabilityLevel::Unstable { issue, .. }, feature, .. }), - ) => { - write!( - w, - "{0} (const: ", - v - ); - if let Some(n) = issue { - write!( - w, - "unstable", + Some(ConstStability { level: StabilityLevel::Unstable { issue, .. }, feature, .. }) => { + let unstable = if let Some(n) = issue { + format!( + r#"unstable"#, n, feature - ); + ) } else { - write!(w, "unstable"); - } - write!(w, ")"); + String::from("unstable") + }; + + Some((String::from("const unstable"), format!("const: {}", unstable))) } - // stable - (Some(v), _) if ver != containing_ver => { - write!( - w, - "{0}", - v - ); + _ => None, + }; + + if let Some((const_title, const_stability)) = const_title_and_stability { + if !title.is_empty() { + title.push_str(&format!(", {}", const_title)); + } else { + title.push_str(&const_title); + } + + if !stability.is_empty() { + stability.push_str(&format!(" ({})", const_stability)); + } else { + stability.push_str(&const_stability); } - _ => return false, } - true + + if !stability.is_empty() { + write!(w, r#"{}"#, title, stability); + } + + !stability.is_empty() } fn render_assoc_item( -- cgit 1.4.1-3-g733a5 From 152e8889052adaaa6c12652486292be34059713c Mon Sep 17 00:00:00 2001 From: Jacob Hoffman-Andrews Date: Thu, 13 Jan 2022 09:54:44 -0800 Subject: Rustdoc mobile: put out-of-band on its own line Before this, the item name and the stability, source link, and "collapse all docs" would compete for room on a single line, resulting in awkward wrapping behavior on mobile. This gives a separate line for that out-of-band information. It also removes the "copy path" icon on mobile to make a little more room. Also, switch to flex-wrap: wrap, so anytime there's not enough room for `source`, it gets bumped to the next line. --- src/librustdoc/html/static/css/rustdoc.css | 29 +++++++++++++++++++--------- src/test/rustdoc-gui/mobile.goml | 17 ++++++++++++++++ src/test/rustdoc-gui/toggle-docs-mobile.goml | 12 ++++++------ 3 files changed, 43 insertions(+), 15 deletions(-) create mode 100644 src/test/rustdoc-gui/mobile.goml (limited to 'src/librustdoc/html') diff --git a/src/librustdoc/html/static/css/rustdoc.css b/src/librustdoc/html/static/css/rustdoc.css index 44a9a571fa1..d0244351b59 100644 --- a/src/librustdoc/html/static/css/rustdoc.css +++ b/src/librustdoc/html/static/css/rustdoc.css @@ -148,11 +148,11 @@ h1.fqn { } .main-heading { display: flex; + flex-wrap: wrap; + justify-content: space-between; + border-bottom: 1px dashed #DDDDDD; + padding-bottom: 6px; margin-bottom: 15px; - - /* workaround to keep flex from breaking below 700 px width due to the float: right on the nav - above the h1 */ - padding-left: 1px; } .main-heading a:hover { text-decoration: underline; @@ -623,11 +623,7 @@ nav.sub { .content .out-of-band { flex-grow: 0; - text-align: right; - margin-left: auto; - margin-right: 0; font-size: 1.15rem; - padding: 0 0 0 12px; font-weight: normal; float: right; } @@ -1748,10 +1744,25 @@ details.rustdoc-toggle[open] > summary.hideme::after { padding-top: 0px; } - .rustdoc { + .rustdoc, + .main-heading { flex-direction: column; } + .content .out-of-band { + text-align: left; + margin-left: initial; + padding: initial; + } + + .content .out-of-band .since::before { + content: "Since "; + } + + #copy-path { + display: none; + } + /* Hide the logo and item name from the sidebar. Those are displayed in the mobile-topbar instead. */ .sidebar .sidebar-logo, diff --git a/src/test/rustdoc-gui/mobile.goml b/src/test/rustdoc-gui/mobile.goml new file mode 100644 index 00000000000..acde1123925 --- /dev/null +++ b/src/test/rustdoc-gui/mobile.goml @@ -0,0 +1,17 @@ +// Test various properties of the mobile UI +goto: file://|DOC_PATH|/staged_api/struct.Foo.html +size: (400, 600) + +// The out-of-band info (source, stable version, collapse) should be below the +// h1 when the screen gets narrow enough. +assert-css: (".main-heading", { + "display": "flex", + "flex-direction": "column" +}) + +// Note: We can't use assert-text here because the 'Since' is set by CSS and +// is therefore not part of the DOM. +assert-css: (".content .out-of-band .since::before", { "content": "\"Since \"" }) + +size: (1000, 1000) +assert-css-false: (".content .out-of-band .since::before", { "content": "\"Since \"" }) diff --git a/src/test/rustdoc-gui/toggle-docs-mobile.goml b/src/test/rustdoc-gui/toggle-docs-mobile.goml index 4c83fd6c0e3..e7a75b43c5a 100644 --- a/src/test/rustdoc-gui/toggle-docs-mobile.goml +++ b/src/test/rustdoc-gui/toggle-docs-mobile.goml @@ -1,12 +1,12 @@ goto: file://|DOC_PATH|/test_docs/struct.Foo.html size: (433, 600) assert-attribute: (".top-doc", {"open": ""}) -click: (4, 250) // This is the position of the top doc comment toggle +click: (4, 270) // This is the position of the top doc comment toggle assert-attribute-false: (".top-doc", {"open": ""}) -click: (4, 250) +click: (4, 270) assert-attribute: (".top-doc", {"open": ""}) // To ensure that the toggle isn't over the text, we check that the toggle isn't clicked. -click: (3, 250) +click: (3, 270) assert-attribute: (".top-doc", {"open": ""}) // Assert the position of the toggle on the top doc block. @@ -22,10 +22,10 @@ assert-position: ( // Now we do the same but with a little bigger width size: (600, 600) assert-attribute: (".top-doc", {"open": ""}) -click: (4, 250) // New Y position since all search elements are back on one line. +click: (4, 270) // New Y position since all search elements are back on one line. assert-attribute-false: (".top-doc", {"open": ""}) -click: (4, 250) +click: (4, 270) assert-attribute: (".top-doc", {"open": ""}) // To ensure that the toggle isn't over the text, we check that the toggle isn't clicked. -click: (3, 250) +click: (3, 270) assert-attribute: (".top-doc", {"open": ""}) -- cgit 1.4.1-3-g733a5