Skip to content

Commit d19aeb2

Browse files
jshacuviper
jsha
authored and
cuviper
committed
Fix documentation header sizes
And add a rustdoc-gui test confirming various header sizes. (cherry picked from commit 89276ff)
1 parent d658d6d commit d19aeb2

File tree

5 files changed

+238
-11
lines changed

5 files changed

+238
-11
lines changed

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1596,7 +1596,7 @@ fn render_impl(
15961596
error_codes: cx.shared.codes,
15971597
edition: cx.shared.edition(),
15981598
playground: &cx.shared.playground,
1599-
heading_offset: HeadingOffset::H2
1599+
heading_offset: HeadingOffset::H4
16001600
}
16011601
.into_string()
16021602
);

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -960,7 +960,7 @@ fn item_union(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, s: &clean::Uni
960960
if let Some(stability_class) = field.stability_class(cx.tcx()) {
961961
write!(w, "<span class=\"stab {stab}\"></span>", stab = stability_class);
962962
}
963-
document(w, cx, field, Some(it), HeadingOffset::H2);
963+
document(w, cx, field, Some(it), HeadingOffset::H3);
964964
}
965965
}
966966
let def_id = it.def_id.expect_def_id();
@@ -1071,7 +1071,7 @@ fn item_enum(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, e: &clean::Enum
10711071
w.write_str("</code>");
10721072
render_stability_since(w, variant, it, cx.tcx());
10731073
w.write_str("</div>");
1074-
document(w, cx, variant, Some(it), HeadingOffset::H2);
1074+
document(w, cx, variant, Some(it), HeadingOffset::H3);
10751075
document_non_exhaustive(w, variant);
10761076

10771077
use crate::clean::Variant;
@@ -1111,7 +1111,7 @@ fn item_enum(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, e: &clean::Enum
11111111
f = field.name.as_ref().unwrap(),
11121112
t = ty.print(cx)
11131113
);
1114-
document(w, cx, field, Some(variant), HeadingOffset::H2);
1114+
document(w, cx, field, Some(variant), HeadingOffset::H4);
11151115
}
11161116
_ => unreachable!(),
11171117
}
@@ -1258,7 +1258,7 @@ fn item_struct(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, s: &clean::St
12581258
name = field_name,
12591259
ty = ty.print(cx)
12601260
);
1261-
document(w, cx, field, Some(it), HeadingOffset::H2);
1261+
document(w, cx, field, Some(it), HeadingOffset::H3);
12621262
}
12631263
}
12641264
}

‎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": "16px"})
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": "16px"})
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": "16px"})
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": "16px"})
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": "16px"})
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: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,14 @@ assert-text: (".sidebar-elems > #all-types", "See all test_docs's items")
77
assert-text: (".sidebar-elems > .crate > ul > li > a.current", "test_docs")
88
// And we're also supposed to have the list of items in the current module.
99
assert-text: (".sidebar-elems > .items > ul > li:nth-child(1)", "Modules")
10-
assert-text: (".sidebar-elems > .items > ul > li:nth-child(2)", "Structs")
11-
assert-text: (".sidebar-elems > .items > ul > li:nth-child(3)", "Enums")
12-
assert-text: (".sidebar-elems > .items > ul > li:nth-child(4)", "Traits")
13-
assert-text: (".sidebar-elems > .items > ul > li:nth-child(5)", "Functions")
14-
assert-text: (".sidebar-elems > .items > ul > li:nth-child(6)", "Type Definitions")
15-
assert-text: (".sidebar-elems > .items > ul > li:nth-child(7)", "Keywords")
10+
assert-text: (".sidebar-elems > .items > ul > li:nth-child(2)", "Macros")
11+
assert-text: (".sidebar-elems > .items > ul > li:nth-child(3)", "Structs")
12+
assert-text: (".sidebar-elems > .items > ul > li:nth-child(4)", "Enums")
13+
assert-text: (".sidebar-elems > .items > ul > li:nth-child(5)", "Traits")
14+
assert-text: (".sidebar-elems > .items > ul > li:nth-child(6)", "Functions")
15+
assert-text: (".sidebar-elems > .items > ul > li:nth-child(7)", "Type Definitions")
16+
assert-text: (".sidebar-elems > .items > ul > li:nth-child(8)", "Unions")
17+
assert-text: (".sidebar-elems > .items > ul > li:nth-child(9)", "Keywords")
1618
assert-text: ("#structs + .item-table .item-left > a", "Foo")
1719
click: "#structs + .item-table .item-left > a"
1820

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

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,3 +123,129 @@ pub mod huge_amount_of_consts {
123123

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

0 commit comments

Comments
 (0)