Skip to content

Commit

Permalink
Auto merge of rust-lang#90186 - jsha:fix-header-sizes, r=GuillaumeGomez
Browse files Browse the repository at this point in the history
Fix documentation header sizes

And add a rustdoc-gui test confirming various header sizes.

Split off from rust-lang#90156. This fixes a regression in rust-lang#89506 where the heading level of titles within Markdown was too high (h2) for docblocks under structs, unions, and enum impls.

r? `@camelid`

Demo: https://jacob.hoffman-andrews.com/rust/fix-header-sizes/std/string/struct.String.html#impl-Add%3C%26%27_%20str%3E
Stable: https://doc.rust-lang.org/stable/std/string/struct.String.html#impl-Add%3C%26%27_%20str%3E
Beta: https://doc.rust-lang.org/beta/std/string/struct.String.html#impl-Add%3C%26%27_%20str%3E
  • Loading branch information
bors committed Oct 27, 2021
2 parents a8f6e61 + 89276ff commit 337e156
Show file tree
Hide file tree
Showing 5 changed files with 232 additions and 6 deletions.
2 changes: 1 addition & 1 deletion src/librustdoc/html/render/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1612,7 +1612,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()
);
Expand Down
8 changes: 4 additions & 4 deletions src/librustdoc/html/render/print_item.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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, "<span class=\"stab {stab}\"></span>", 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();
Expand Down Expand Up @@ -1094,7 +1094,7 @@ fn item_enum(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, e: &clean::Enum
w.write_str("</code>");
render_stability_since(w, variant, it, cx.tcx());
w.write_str("</div>");
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;
Expand Down Expand Up @@ -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!(),
}
Expand Down Expand Up @@ -1286,7 +1286,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);
}
}
}
Expand Down
99 changes: 99 additions & 0 deletions src/test/rustdoc-gui/header-size.goml
Original file line number Diff line number Diff line change
@@ -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"})

assert-css: ("h2#top-doc-prose-title", {"font-size": "20.8px"})
assert-css: ("h3#top-doc-prose-sub-heading", {"font-size": "18.4px"})
assert-css: ("h4#top-doc-prose-sub-sub-heading", {"font-size": "17.6px"})

assert-css: ("h2#fields", {"font-size": "22.4px"})
assert-css: ("h3#title-for-field", {"font-size": "20.8px"})
assert-css: ("h4#sub-heading-for-field", {"font-size": "16px"})

assert-css: ("h2#implementations", {"font-size": "22.4px"})

assert-css: ("#impl > h3.code-header", {"font-size": "17.6px"})
assert-css: ("#method\.do_nothing > h4.code-header", {"font-size": "16px"})

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"})

assert-css: ("h5#title-for-struct-impl-item-doc", {"font-size": "16px"})
assert-css: ("h6#sub-heading-for-struct-impl-item-doc", {"font-size": "15.2px"})
assert-css: ("h6#sub-sub-heading-for-struct-impl-item-doc", {"font-size": "15.2px"})

goto: file://|DOC_PATH|/test_docs/enum.HeavilyDocumentedEnum.html

assert-css: ("h1.fqn", {"font-size": "24px"})

assert-css: ("h2#top-doc-prose-title", {"font-size": "20.8px"})
assert-css: ("h3#top-doc-prose-sub-heading", {"font-size": "18.4px"})
assert-css: ("h4#top-doc-prose-sub-sub-heading", {"font-size": "17.6px"})

assert-css: ("h2#variants", {"font-size": "22.4px"})

assert-css: ("h3#none-prose-title", {"font-size": "20.8px"})
assert-css: ("h4#none-prose-sub-heading", {"font-size": "16px"})

assert-css: ("h3#wrapped-prose-title", {"font-size": "20.8px"})
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"})

assert-css: ("#impl > h3.code-header", {"font-size": "17.6px"})
assert-css: ("#method\.do_nothing > h4.code-header", {"font-size": "16px"})

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"})

assert-css: ("h5#title-for-enum-impl-item-doc", {"font-size": "16px"})
assert-css: ("h6#sub-heading-for-enum-impl-item-doc", {"font-size": "15.2px"})
assert-css: ("h6#sub-sub-heading-for-enum-impl-item-doc", {"font-size": "15.2px"})

goto: file://|DOC_PATH|/test_docs/union.HeavilyDocumentedUnion.html

assert-css: ("h1.fqn", {"font-size": "24px"})

assert-css: ("h2#top-doc-prose-title", {"font-size": "20.8px"})
assert-css: ("h3#top-doc-prose-sub-heading", {"font-size": "18.4px"})

assert-css: ("h2#fields", {"font-size": "22.4px"})

assert-css: ("h3#title-for-union-variant", {"font-size": "20.8px"})
assert-css: ("h4#sub-heading-for-union-variant", {"font-size": "16px"})

assert-css: ("h2#implementations", {"font-size": "22.4px"})

assert-css: ("#impl > h3.code-header", {"font-size": "17.6px"})
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"})
assert-css: ("h6#sub-heading-for-union-impl-item-doc", {"font-size": "15.2px"})

goto: file://|DOC_PATH|/test_docs/macro.heavily_documented_macro.html

assert-css: ("h1.fqn", {"font-size": "24px"})

assert-css: ("h2#top-doc-prose-title", {"font-size": "20.8px"})
assert-css: ("h3#top-doc-prose-sub-heading", {"font-size": "18.4px"})
3 changes: 2 additions & 1 deletion src/test/rustdoc-gui/sidebar.goml
Original file line number Diff line number Diff line change
Expand Up @@ -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"

Expand Down
126 changes: 126 additions & 0 deletions src/test/rustdoc-gui/src/test_docs/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
() => {};
}

0 comments on commit 337e156

Please sign in to comment.