From b7a948da4c91549d92e6c02c45dae8c7395a4bcd Mon Sep 17 00:00:00 2001 From: Jacob Hoffman-Andrews Date: Fri, 22 Oct 2021 13:45:10 -0700 Subject: [PATCH] Fix documentation header sizes And add a rustdoc-gui test confirming various header sizes. --- src/librustdoc/html/render/mod.rs | 2 +- src/librustdoc/html/render/print_item.rs | 8 +- src/test/rustdoc-gui/header-size.goml | 99 +++++++++++++++++ src/test/rustdoc-gui/sidebar.goml | 3 +- src/test/rustdoc-gui/src/test_docs/lib.rs | 126 ++++++++++++++++++++++ 5 files changed, 232 insertions(+), 6 deletions(-) create mode 100644 src/test/rustdoc-gui/header-size.goml diff --git a/src/librustdoc/html/render/mod.rs b/src/librustdoc/html/render/mod.rs index 69c5c2c4abc2a..2898da1cbf81f 100644 --- a/src/librustdoc/html/render/mod.rs +++ b/src/librustdoc/html/render/mod.rs @@ -1596,7 +1596,7 @@ fn render_impl( error_codes: cx.shared.codes, edition: cx.shared.edition(), playground: &cx.shared.playground, - heading_offset: HeadingOffset::H2 + heading_offset: HeadingOffset::H4 } .into_string() ); diff --git a/src/librustdoc/html/render/print_item.rs b/src/librustdoc/html/render/print_item.rs index 58cd1018c316f..3fffbbefb1cb9 100644 --- a/src/librustdoc/html/render/print_item.rs +++ b/src/librustdoc/html/render/print_item.rs @@ -983,7 +983,7 @@ fn item_union(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, s: &clean::Uni if let Some(stability_class) = field.stability_class(cx.tcx()) { write!(w, "", stab = stability_class); } - document(w, cx, field, Some(it), HeadingOffset::H2); + document(w, cx, field, Some(it), HeadingOffset::H3); } } let def_id = it.def_id.expect_def_id(); @@ -1094,7 +1094,7 @@ fn item_enum(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, e: &clean::Enum w.write_str(""); render_stability_since(w, variant, it, cx.tcx()); w.write_str(""); - document(w, cx, variant, Some(it), HeadingOffset::H2); + document(w, cx, variant, Some(it), HeadingOffset::H3); document_non_exhaustive(w, variant); use crate::clean::Variant; @@ -1134,7 +1134,7 @@ fn item_enum(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, e: &clean::Enum f = field.name.as_ref().unwrap(), t = ty.print(cx) ); - document(w, cx, field, Some(variant), HeadingOffset::H2); + document(w, cx, field, Some(variant), HeadingOffset::H4); } _ => unreachable!(), } @@ -1285,7 +1285,7 @@ fn item_struct(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, s: &clean::St name = field_name, ty = ty.print(cx) ); - document(w, cx, field, Some(it), HeadingOffset::H2); + document(w, cx, field, Some(it), HeadingOffset::H3); } } } diff --git a/src/test/rustdoc-gui/header-size.goml b/src/test/rustdoc-gui/header-size.goml new file mode 100644 index 0000000000000..bd865e2c4f2d7 --- /dev/null +++ b/src/test/rustdoc-gui/header-size.goml @@ -0,0 +1,99 @@ +// This test check that headers (a) have the correct heading level, and (b) are the right size. +// The sizes may change as design changes, but try to make sure a lower header is never bigger than +// its parent headers. +// Most of these sizes are set in CSS in `em` units, so here's a conversion chart based on our +// default 16px font size: +// 24px 1.5em +// 22.4px 1.4em +// 20.8px 1.3em +// 18.4px 1.15em +// 17.6px 1.1em +// 16px 1em +// 15.2px 0.95em +goto: file://|DOC_PATH|/test_docs/struct.HeavilyDocumentedStruct.html + +assert-css: ("h1.fqn", {"font-size": "24px"}) // 1.5em + +assert-css: ("h2#top-doc-prose-title", {"font-size": "20.8px"}) // 1.3em +assert-css: ("h3#top-doc-prose-sub-heading", {"font-size": "18.4px"}) // 1.15em +assert-css: ("h4#top-doc-prose-sub-sub-heading", {"font-size": "17.6px"}) // 1.1em + +assert-css: ("h2#fields", {"font-size": "22.4px"}) // 1.4em +assert-css: ("h3#title-for-field", {"font-size": "20.8px"}) // 1.3em +assert-css: ("h4#sub-heading-for-field", {"font-size": "16px"}) + +assert-css: ("h2#implementations", {"font-size": "22.4px"}) // 1.4em + +assert-css: ("#impl > h3.code-header", {"font-size": "16px"}) // 1em +assert-css: ("#method\.do_nothing > h4.code-header", {"font-size": "16px"}) // 1em + +assert-css: ("h4#title-for-struct-impl-doc", {"font-size": "16px"}) +assert-css: ("h5#sub-heading-for-struct-impl-doc", {"font-size": "16px"}) +assert-css: ("h6#sub-sub-heading-for-struct-impl-doc", {"font-size": "15.2px"}) // 0.95em + +assert-css: ("h5#title-for-struct-impl-item-doc", {"font-size": "16px"}) // 1em +assert-css: ("h6#sub-heading-for-struct-impl-item-doc", {"font-size": "15.2px"}) // 0.95em +assert-css: ("h6#sub-sub-heading-for-struct-impl-item-doc", {"font-size": "15.2px"}) // 0.95em + +goto: file://|DOC_PATH|/test_docs/enum.HeavilyDocumentedEnum.html + +assert-css: ("h1.fqn", {"font-size": "24px"}) // 1.5em + +assert-css: ("h2#top-doc-prose-title", {"font-size": "20.8px"}) // 1.3em +assert-css: ("h3#top-doc-prose-sub-heading", {"font-size": "18.4px"}) // 1.15em +assert-css: ("h4#top-doc-prose-sub-sub-heading", {"font-size": "17.6px"}) // 1.1em + +assert-css: ("h2#variants", {"font-size": "22.4px"}) // 1.4em + +assert-css: ("h3#none-prose-title", {"font-size": "20.8px"}) // 1.3em +assert-css: ("h4#none-prose-sub-heading", {"font-size": "16px"}) + +assert-css: ("h3#wrapped-prose-title", {"font-size": "20.8px"}) // 1.3em +assert-css: ("h4#wrapped-prose-sub-heading", {"font-size": "16px"}) + +assert-css: ("h4#wrapped0-prose-title", {"font-size": "16px"}) +assert-css: ("h5#wrapped0-prose-sub-heading", {"font-size": "16px"}) + +assert-css: ("h4#structy-prose-title", {"font-size": "16px"}) +assert-css: ("h5#structy-prose-sub-heading", {"font-size": "16px"}) + +assert-css: ("h2#implementations", {"font-size": "22.4px"}) // 1.4em + +assert-css: ("#impl > h3.code-header", {"font-size": "16px"}) // 1em +assert-css: ("#method\.do_nothing > h4.code-header", {"font-size": "16px"}) // 1em + +assert-css: ("h4#title-for-enum-impl-doc", {"font-size": "16px"}) +assert-css: ("h5#sub-heading-for-enum-impl-doc", {"font-size": "16px"}) +assert-css: ("h6#sub-sub-heading-for-enum-impl-doc", {"font-size": "15.2px"}) // 0.95em + +assert-css: ("h5#title-for-enum-impl-item-doc", {"font-size": "16px"}) // 1em +assert-css: ("h6#sub-heading-for-enum-impl-item-doc", {"font-size": "15.2px"}) // 0.95em +assert-css: ("h6#sub-sub-heading-for-enum-impl-item-doc", {"font-size": "15.2px"}) // 0.95em + +goto: file://|DOC_PATH|/test_docs/union.HeavilyDocumentedUnion.html + +assert-css: ("h1.fqn", {"font-size": "24px"}) // 1.5em + +assert-css: ("h2#top-doc-prose-title", {"font-size": "20.8px"}) // 1.3em +assert-css: ("h3#top-doc-prose-sub-heading", {"font-size": "18.4px"}) // 1.15em + +assert-css: ("h2#fields", {"font-size": "22.4px"}) // 1.4em + +assert-css: ("h3#title-for-union-variant", {"font-size": "20.8px"}) // 1.3em +assert-css: ("h4#sub-heading-for-union-variant", {"font-size": "16px"}) + +assert-css: ("h2#implementations", {"font-size": "22.4px"}) // 1.4em + +assert-css: ("#impl > h3.code-header", {"font-size": "16px"}) // 1em +assert-css: ("h4#title-for-union-impl-doc", {"font-size": "16px"}) +assert-css: ("h5#sub-heading-for-union-impl-doc", {"font-size": "16px"}) + +assert-css: ("h5#title-for-union-impl-item-doc", {"font-size": "16px"}) // 1em +assert-css: ("h6#sub-heading-for-union-impl-item-doc", {"font-size": "15.2px"}) // 0.95em + +goto: file://|DOC_PATH|/test_docs/macro.heavily_documented_macro.html + +assert-css: ("h1.fqn", {"font-size": "24px"}) // 1.5em + +assert-css: ("h2#top-doc-prose-title", {"font-size": "20.8px"}) // 1.3em +assert-css: ("h3#top-doc-prose-sub-heading", {"font-size": "18.4px"}) // 1.15em diff --git a/src/test/rustdoc-gui/sidebar.goml b/src/test/rustdoc-gui/sidebar.goml index 62dc76a40bcf5..eacc9f6c15fe1 100644 --- a/src/test/rustdoc-gui/sidebar.goml +++ b/src/test/rustdoc-gui/sidebar.goml @@ -13,7 +13,8 @@ assert-text: (".sidebar-elems > .items > ul > li:nth-child(4)", "Enums") assert-text: (".sidebar-elems > .items > ul > li:nth-child(5)", "Traits") assert-text: (".sidebar-elems > .items > ul > li:nth-child(6)", "Functions") assert-text: (".sidebar-elems > .items > ul > li:nth-child(7)", "Type Definitions") -assert-text: (".sidebar-elems > .items > ul > li:nth-child(8)", "Keywords") +assert-text: (".sidebar-elems > .items > ul > li:nth-child(8)", "Unions") +assert-text: (".sidebar-elems > .items > ul > li:nth-child(9)", "Keywords") assert-text: ("#structs + .item-table .item-left > a", "Foo") click: "#structs + .item-table .item-left > a" diff --git a/src/test/rustdoc-gui/src/test_docs/lib.rs b/src/test/rustdoc-gui/src/test_docs/lib.rs index 652308a71cb85..14d8b18613087 100644 --- a/src/test/rustdoc-gui/src/test_docs/lib.rs +++ b/src/test/rustdoc-gui/src/test_docs/lib.rs @@ -131,3 +131,129 @@ macro_rules! repro { } pub use crate::repro as repro2; + +/// # Top-doc Prose title +/// +/// Text below title. +/// +/// ## Top-doc Prose sub-heading +/// +/// Text below sub-heading. +/// +/// ### Top-doc Prose sub-sub-heading +/// +/// Text below sub-sub-heading +pub struct HeavilyDocumentedStruct { + /// # Title for field + /// ## Sub-heading for field + pub nothing: (), +} + +/// # Title for struct impl doc +/// +/// Text below heading. +/// +/// ## Sub-heading for struct impl doc +/// +/// Text below sub-heading. +/// +/// ### Sub-sub-heading for struct impl doc +/// +/// Text below sub-sub-heading. +/// +impl HeavilyDocumentedStruct { + /// # Title for struct impl-item doc + /// Text below title. + /// ## Sub-heading for struct impl-item doc + /// Text below sub-heading. + /// ### Sub-sub-heading for struct impl-item doc + /// Text below sub-sub-heading. + pub fn do_nothing() {} +} + +/// # Top-doc Prose title +/// +/// Text below title. +/// +/// ## Top-doc Prose sub-heading +/// +/// Text below sub-heading. +/// +/// ### Top-doc Prose sub-sub-heading +/// +/// Text below sub-sub-heading +pub enum HeavilyDocumentedEnum { + /// # None prose title + /// ## None prose sub-heading + None, + /// # Wrapped prose title + /// ## Wrapped prose sub-heading + Wrapped( + /// # Wrapped.0 prose title + /// ## Wrapped.0 prose sub-heading + String, + String, + ), + Structy { + /// # Structy prose title + /// ## Structy prose sub-heading + alpha: String, + beta: String, + }, +} + +/// # Title for enum impl doc +/// +/// Text below heading. +/// +/// ## Sub-heading for enum impl doc +/// +/// Text below sub-heading. +/// +/// ### Sub-sub-heading for enum impl doc +/// +/// Text below sub-sub-heading. +/// +impl HeavilyDocumentedEnum { + /// # Title for enum impl-item doc + /// Text below title. + /// ## Sub-heading for enum impl-item doc + /// Text below sub-heading. + /// ### Sub-sub-heading for enum impl-item doc + /// Text below sub-sub-heading. + pub fn do_nothing() {} +} + +/// # Top-doc prose title +/// +/// Text below heading. +/// +/// ## Top-doc prose sub-heading +/// +/// Text below heading. +pub union HeavilyDocumentedUnion { + /// # Title for union variant + /// ## Sub-heading for union variant + pub nothing: (), + pub something: f32, +} + +/// # Title for union impl doc +/// ## Sub-heading for union impl doc +impl HeavilyDocumentedUnion { + /// # Title for union impl-item doc + /// ## Sub-heading for union impl-item doc + pub fn do_nothing() {} +} + +/// # Top-doc prose title +/// +/// Text below heading. +/// +/// ## Top-doc prose sub-heading +/// +/// Text below heading. +#[macro_export] +macro_rules! heavily_documented_macro { + () => {}; +}