Skip to content

Commit 337e156

Browse files
borsbors
committed
Auto merge of rust-lang#90186 - jsha:fix-header-sizes, r=GuillaumeGomez
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
2 parents a8f6e61 + 89276ff commit 337e156

File tree

5 files changed

+232
-6
lines changed

5 files changed

+232
-6
lines changed

‎src/librustdoc/html/render/mod.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1612,7 +1612,7 @@ fn render_impl(
16121612
error_codes: cx.shared.codes,
16131613
edition: cx.shared.edition(),
16141614
playground: &cx.shared.playground,
1615-
heading_offset: HeadingOffset::H2
1615+
heading_offset: HeadingOffset::H4
16161616
}
16171617
.into_string()
16181618
);

‎src/librustdoc/html/render/print_item.rs‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -983,7 +983,7 @@ fn item_union(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, s: &clean::Uni
983983
if let Some(stability_class) = field.stability_class(cx.tcx()) {
984984
write!(w, "<span class=\"stab {stab}\"></span>", stab = stability_class);
985985
}
986-
document(w, cx, field, Some(it), HeadingOffset::H2);
986+
document(w, cx, field, Some(it), HeadingOffset::H3);
987987
}
988988
}
989989
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
10941094
w.write_str("</code>");
10951095
render_stability_since(w, variant, it, cx.tcx());
10961096
w.write_str("</div>");
1097-
document(w, cx, variant, Some(it), HeadingOffset::H2);
1097+
document(w, cx, variant, Some(it), HeadingOffset::H3);
10981098
document_non_exhaustive(w, variant);
10991099

11001100
use crate::clean::Variant;
@@ -1134,7 +1134,7 @@ fn item_enum(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, e: &clean::Enum
11341134
f = field.name.as_ref().unwrap(),
11351135
t = ty.print(cx)
11361136
);
1137-
document(w, cx, field, Some(variant), HeadingOffset::H2);
1137+
document(w, cx, field, Some(variant), HeadingOffset::H4);
11381138
}
11391139
_ => unreachable!(),
11401140
}
@@ -1286,7 +1286,7 @@ fn item_struct(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, s: &clean::St
12861286
name = field_name,
12871287
ty = ty.print(cx)
12881288
);
1289-
document(w, cx, field, Some(it), HeadingOffset::H2);
1289+
document(w, cx, field, Some(it), HeadingOffset::H3);
12901290
}
12911291
}
12921292
}

‎src/test/rustdoc-gui/header-size.goml‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
// This test check that headers (a) have the correct heading level, and (b) are the right size.
2+
// The sizes may change as design changes, but try to make sure a lower header is never bigger than
3+
// its parent headers.
4+
// Most of these sizes are set in CSS in `em` units, so here's a conversion chart based on our
5+
// default 16px font size:
6+
// 24px 1.5em
7+
// 22.4px 1.4em
8+
// 20.8px 1.3em
9+
// 18.4px 1.15em
10+
// 17.6px 1.1em
11+
// 16px 1em
12+
// 15.2px 0.95em
13+
goto: file://|DOC_PATH|/test_docs/struct.HeavilyDocumentedStruct.html
14+
15+
assert-css: ("h1.fqn", {"font-size": "24px"})
16+
17+
assert-css: ("h2#top-doc-prose-title", {"font-size": "20.8px"})
18+
assert-css: ("h3#top-doc-prose-sub-heading", {"font-size": "18.4px"})
19+
assert-css: ("h4#top-doc-prose-sub-sub-heading", {"font-size": "17.6px"})
20+
21+
assert-css: ("h2#fields", {"font-size": "22.4px"})
22+
assert-css: ("h3#title-for-field", {"font-size": "20.8px"})
23+
assert-css: ("h4#sub-heading-for-field", {"font-size": "16px"})
24+
25+
assert-css: ("h2#implementations", {"font-size": "22.4px"})
26+
27+
assert-css: ("#impl > h3.code-header", {"font-size": "17.6px"})
28+
assert-css: ("#method\.do_nothing > h4.code-header", {"font-size": "16px"})
29+
30+
assert-css: ("h4#title-for-struct-impl-doc", {"font-size": "16px"})
31+
assert-css: ("h5#sub-heading-for-struct-impl-doc", {"font-size": "16px"})
32+
assert-css: ("h6#sub-sub-heading-for-struct-impl-doc", {"font-size": "15.2px"})
33+
34+
assert-css: ("h5#title-for-struct-impl-item-doc", {"font-size": "16px"})
35+
assert-css: ("h6#sub-heading-for-struct-impl-item-doc", {"font-size": "15.2px"})
36+
assert-css: ("h6#sub-sub-heading-for-struct-impl-item-doc", {"font-size": "15.2px"})
37+
38+
goto: file://|DOC_PATH|/test_docs/enum.HeavilyDocumentedEnum.html
39+
40+
assert-css: ("h1.fqn", {"font-size": "24px"})
41+
42+
assert-css: ("h2#top-doc-prose-title", {"font-size": "20.8px"})
43+
assert-css: ("h3#top-doc-prose-sub-heading", {"font-size": "18.4px"})
44+
assert-css: ("h4#top-doc-prose-sub-sub-heading", {"font-size": "17.6px"})
45+
46+
assert-css: ("h2#variants", {"font-size": "22.4px"})
47+
48+
assert-css: ("h3#none-prose-title", {"font-size": "20.8px"})
49+
assert-css: ("h4#none-prose-sub-heading", {"font-size": "16px"})
50+
51+
assert-css: ("h3#wrapped-prose-title", {"font-size": "20.8px"})
52+
assert-css: ("h4#wrapped-prose-sub-heading", {"font-size": "16px"})
53+
54+
assert-css: ("h4#wrapped0-prose-title", {"font-size": "16px"})
55+
assert-css: ("h5#wrapped0-prose-sub-heading", {"font-size": "16px"})
56+
57+
assert-css: ("h4#structy-prose-title", {"font-size": "16px"})
58+
assert-css: ("h5#structy-prose-sub-heading", {"font-size": "16px"})
59+
60+
assert-css: ("h2#implementations", {"font-size": "22.4px"})
61+
62+
assert-css: ("#impl > h3.code-header", {"font-size": "17.6px"})
63+
assert-css: ("#method\.do_nothing > h4.code-header", {"font-size": "16px"})
64+
65+
assert-css: ("h4#title-for-enum-impl-doc", {"font-size": "16px"})
66+
assert-css: ("h5#sub-heading-for-enum-impl-doc", {"font-size": "16px"})
67+
assert-css: ("h6#sub-sub-heading-for-enum-impl-doc", {"font-size": "15.2px"})
68+
69+
assert-css: ("h5#title-for-enum-impl-item-doc", {"font-size": "16px"})
70+
assert-css: ("h6#sub-heading-for-enum-impl-item-doc", {"font-size": "15.2px"})
71+
assert-css: ("h6#sub-sub-heading-for-enum-impl-item-doc", {"font-size": "15.2px"})
72+
73+
goto: file://|DOC_PATH|/test_docs/union.HeavilyDocumentedUnion.html
74+
75+
assert-css: ("h1.fqn", {"font-size": "24px"})
76+
77+
assert-css: ("h2#top-doc-prose-title", {"font-size": "20.8px"})
78+
assert-css: ("h3#top-doc-prose-sub-heading", {"font-size": "18.4px"})
79+
80+
assert-css: ("h2#fields", {"font-size": "22.4px"})
81+
82+
assert-css: ("h3#title-for-union-variant", {"font-size": "20.8px"})
83+
assert-css: ("h4#sub-heading-for-union-variant", {"font-size": "16px"})
84+
85+
assert-css: ("h2#implementations", {"font-size": "22.4px"})
86+
87+
assert-css: ("#impl > h3.code-header", {"font-size": "17.6px"})
88+
assert-css: ("h4#title-for-union-impl-doc", {"font-size": "16px"})
89+
assert-css: ("h5#sub-heading-for-union-impl-doc", {"font-size": "16px"})
90+
91+
assert-css: ("h5#title-for-union-impl-item-doc", {"font-size": "16px"})
92+
assert-css: ("h6#sub-heading-for-union-impl-item-doc", {"font-size": "15.2px"})
93+
94+
goto: file://|DOC_PATH|/test_docs/macro.heavily_documented_macro.html
95+
96+
assert-css: ("h1.fqn", {"font-size": "24px"})
97+
98+
assert-css: ("h2#top-doc-prose-title", {"font-size": "20.8px"})
99+
assert-css: ("h3#top-doc-prose-sub-heading", {"font-size": "18.4px"})

‎src/test/rustdoc-gui/sidebar.goml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,8 @@ assert-text: (".sidebar-elems > .items > ul > li:nth-child(4)", "Enums")
1313
assert-text: (".sidebar-elems > .items > ul > li:nth-child(5)", "Traits")
1414
assert-text: (".sidebar-elems > .items > ul > li:nth-child(6)", "Functions")
1515
assert-text: (".sidebar-elems > .items > ul > li:nth-child(7)", "Type Definitions")
16-
assert-text: (".sidebar-elems > .items > ul > li:nth-child(8)", "Keywords")
16+
assert-text: (".sidebar-elems > .items > ul > li:nth-child(8)", "Unions")
17+
assert-text: (".sidebar-elems > .items > ul > li:nth-child(9)", "Keywords")
1718
assert-text: ("#structs + .item-table .item-left > a", "Foo")
1819
click: "#structs + .item-table .item-left > a"
1920

‎src/test/rustdoc-gui/src/test_docs/lib.rs‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -131,3 +131,129 @@ macro_rules! repro {
131131
}
132132

133133
pub use crate::repro as repro2;
134+
135+
/// # Top-doc Prose title
136+
///
137+
/// Text below title.
138+
///
139+
/// ## Top-doc Prose sub-heading
140+
///
141+
/// Text below sub-heading.
142+
///
143+
/// ### Top-doc Prose sub-sub-heading
144+
///
145+
/// Text below sub-sub-heading
146+
pub struct HeavilyDocumentedStruct {
147+
/// # Title for field
148+
/// ## Sub-heading for field
149+
pub nothing: (),
150+
}
151+
152+
/// # Title for struct impl doc
153+
///
154+
/// Text below heading.
155+
///
156+
/// ## Sub-heading for struct impl doc
157+
///
158+
/// Text below sub-heading.
159+
///
160+
/// ### Sub-sub-heading for struct impl doc
161+
///
162+
/// Text below sub-sub-heading.
163+
///
164+
impl HeavilyDocumentedStruct {
165+
/// # Title for struct impl-item doc
166+
/// Text below title.
167+
/// ## Sub-heading for struct impl-item doc
168+
/// Text below sub-heading.
169+
/// ### Sub-sub-heading for struct impl-item doc
170+
/// Text below sub-sub-heading.
171+
pub fn do_nothing() {}
172+
}
173+
174+
/// # Top-doc Prose title
175+
///
176+
/// Text below title.
177+
///
178+
/// ## Top-doc Prose sub-heading
179+
///
180+
/// Text below sub-heading.
181+
///
182+
/// ### Top-doc Prose sub-sub-heading
183+
///
184+
/// Text below sub-sub-heading
185+
pub enum HeavilyDocumentedEnum {
186+
/// # None prose title
187+
/// ## None prose sub-heading
188+
None,
189+
/// # Wrapped prose title
190+
/// ## Wrapped prose sub-heading
191+
Wrapped(
192+
/// # Wrapped.0 prose title
193+
/// ## Wrapped.0 prose sub-heading
194+
String,
195+
String,
196+
),
197+
Structy {
198+
/// # Structy prose title
199+
/// ## Structy prose sub-heading
200+
alpha: String,
201+
beta: String,
202+
},
203+
}
204+
205+
/// # Title for enum impl doc
206+
///
207+
/// Text below heading.
208+
///
209+
/// ## Sub-heading for enum impl doc
210+
///
211+
/// Text below sub-heading.
212+
///
213+
/// ### Sub-sub-heading for enum impl doc
214+
///
215+
/// Text below sub-sub-heading.
216+
///
217+
impl HeavilyDocumentedEnum {
218+
/// # Title for enum impl-item doc
219+
/// Text below title.
220+
/// ## Sub-heading for enum impl-item doc
221+
/// Text below sub-heading.
222+
/// ### Sub-sub-heading for enum impl-item doc
223+
/// Text below sub-sub-heading.
224+
pub fn do_nothing() {}
225+
}
226+
227+
/// # Top-doc prose title
228+
///
229+
/// Text below heading.
230+
///
231+
/// ## Top-doc prose sub-heading
232+
///
233+
/// Text below heading.
234+
pub union HeavilyDocumentedUnion {
235+
/// # Title for union variant
236+
/// ## Sub-heading for union variant
237+
pub nothing: (),
238+
pub something: f32,
239+
}
240+
241+
/// # Title for union impl doc
242+
/// ## Sub-heading for union impl doc
243+
impl HeavilyDocumentedUnion {
244+
/// # Title for union impl-item doc
245+
/// ## Sub-heading for union impl-item doc
246+
pub fn do_nothing() {}
247+
}
248+
249+
/// # Top-doc prose title
250+
///
251+
/// Text below heading.
252+
///
253+
/// ## Top-doc prose sub-heading
254+
///
255+
/// Text below heading.
256+
#[macro_export]
257+
macro_rules! heavily_documented_macro {
258+
() => {};
259+
}

0 commit comments

Comments
 (0)