Skip to content

Commit f1425c7

Browse files
author
Mukund Lakshman
committed
heading_level: u32 -> heading_offset: HeadingOffset
1 parent 13558ee commit f1425c7

File tree

7 files changed

+88
-61
lines changed

7 files changed

+88
-61
lines changed

‎src/librustdoc/externalfiles.rs

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
use crate::html::markdown::{ErrorCodes, IdMap, Markdown, Playground};
1+
use crate::html::markdown::{ErrorCodes, HeadingOffset, IdMap, Markdown, Playground};
22
use crate::rustc_span::edition::Edition;
33
use std::fs;
44
use std::path::Path;
@@ -46,7 +46,7 @@ impl ExternalHtml {
4646
error_codes: codes,
4747
edition,
4848
playground,
49-
heading_level: 1
49+
heading_offset: HeadingOffset::H2,
5050
}
5151
.into_string()
5252
);
@@ -62,7 +62,7 @@ impl ExternalHtml {
6262
error_codes: codes,
6363
edition,
6464
playground,
65-
heading_level: 1
65+
heading_offset: HeadingOffset::H2,
6666
}
6767
.into_string()
6868
);

‎src/librustdoc/html/markdown.rs

+28-13
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
//! extern crate rustc_span;
99
//!
1010
//! use rustc_span::edition::Edition;
11-
//! use rustdoc::html::markdown::{IdMap, Markdown, ErrorCodes};
11+
//! use rustdoc::html::markdown::{HeadingOffset, IdMap, Markdown, ErrorCodes};
1212
//!
1313
//! let s = "My *markdown* _text_";
1414
//! let mut id_map = IdMap::new();
@@ -19,7 +19,7 @@
1919
//! error_codes: ErrorCodes::Yes,
2020
//! edition: Edition::Edition2015,
2121
//! playground: &None,
22-
//! heading_level: 1
22+
//! heading_offset: HeadingOffset::H2,
2323
//! };
2424
//! let html = md.into_string();
2525
//! // ... something using html
@@ -75,6 +75,16 @@ pub(crate) fn summary_opts() -> Options {
7575
| Options::ENABLE_SMART_PUNCTUATION
7676
}
7777

78+
#[derive(Debug, Clone, Copy)]
79+
pub enum HeadingOffset {
80+
H1 = 0,
81+
H2,
82+
H3,
83+
H4,
84+
H5,
85+
H6,
86+
}
87+
7888
/// When `to_string` is called, this struct will emit the HTML corresponding to
7989
/// the rendered version of the contained markdown string.
8090
pub struct Markdown<'a> {
@@ -89,8 +99,8 @@ pub struct Markdown<'a> {
8999
pub edition: Edition,
90100
pub playground: &'a Option<Playground>,
91101
/// Offset at which we render headings.
92-
/// E.g. if `heading_level: 1`, then `# something` renders an `<h2>` instead of `<h1>`
93-
pub heading_level: u32,
102+
/// E.g. if `heading_offset: HeadingOffset::H2`, then `# something` renders an `<h2>`.
103+
pub heading_offset: HeadingOffset,
94104
}
95105
/// A tuple struct like `Markdown` that renders the markdown with a table of contents.
96106
crate struct MarkdownWithToc<'a>(
@@ -502,12 +512,17 @@ struct HeadingLinks<'a, 'b, 'ids, I> {
502512
toc: Option<&'b mut TocBuilder>,
503513
buf: VecDeque<SpannedEvent<'a>>,
504514
id_map: &'ids mut IdMap,
505-
level: u32,
515+
heading_offset: HeadingOffset,
506516
}
507517

508518
impl<'a, 'b, 'ids, I> HeadingLinks<'a, 'b, 'ids, I> {
509-
fn new(iter: I, toc: Option<&'b mut TocBuilder>, ids: &'ids mut IdMap, level: u32) -> Self {
510-
HeadingLinks { inner: iter, toc, buf: VecDeque::new(), id_map: ids, level }
519+
fn new(
520+
iter: I,
521+
toc: Option<&'b mut TocBuilder>,
522+
ids: &'ids mut IdMap,
523+
heading_offset: HeadingOffset,
524+
) -> Self {
525+
HeadingLinks { inner: iter, toc, buf: VecDeque::new(), id_map: ids, heading_offset }
511526
}
512527
}
513528

@@ -544,7 +559,7 @@ impl<'a, 'b, 'ids, I: Iterator<Item = SpannedEvent<'a>>> Iterator
544559
self.buf.push_front((Event::Html(format!("{} ", sec).into()), 0..0));
545560
}
546561

547-
let level = std::cmp::min(level + self.level, MAX_HEADER_LEVEL);
562+
let level = std::cmp::min(level + (self.heading_offset as u32), MAX_HEADER_LEVEL);
548563
self.buf.push_back((Event::Html(format!("</a></h{}>", level).into()), 0..0));
549564

550565
let start_tags = format!(
@@ -1027,7 +1042,7 @@ impl Markdown<'_> {
10271042
error_codes: codes,
10281043
edition,
10291044
playground,
1030-
heading_level,
1045+
heading_offset,
10311046
} = self;
10321047

10331048
// This is actually common enough to special-case
@@ -1049,7 +1064,7 @@ impl Markdown<'_> {
10491064

10501065
let mut s = String::with_capacity(md.len() * 3 / 2);
10511066

1052-
let p = HeadingLinks::new(p, None, &mut ids, heading_level);
1067+
let p = HeadingLinks::new(p, None, &mut ids, heading_offset);
10531068
let p = Footnotes::new(p);
10541069
let p = LinkReplacer::new(p.map(|(ev, _)| ev), links);
10551070
let p = TableWrapper::new(p);
@@ -1071,7 +1086,7 @@ impl MarkdownWithToc<'_> {
10711086
let mut toc = TocBuilder::new();
10721087

10731088
{
1074-
let p = HeadingLinks::new(p, Some(&mut toc), &mut ids, 0);
1089+
let p = HeadingLinks::new(p, Some(&mut toc), &mut ids, HeadingOffset::H1);
10751090
let p = Footnotes::new(p);
10761091
let p = TableWrapper::new(p.map(|(ev, _)| ev));
10771092
let p = CodeBlocks::new(p, codes, edition, playground);
@@ -1100,7 +1115,7 @@ impl MarkdownHtml<'_> {
11001115

11011116
let mut s = String::with_capacity(md.len() * 3 / 2);
11021117

1103-
let p = HeadingLinks::new(p, None, &mut ids, 0);
1118+
let p = HeadingLinks::new(p, None, &mut ids, HeadingOffset::H1);
11041119
let p = Footnotes::new(p);
11051120
let p = TableWrapper::new(p.map(|(ev, _)| ev));
11061121
let p = CodeBlocks::new(p, codes, edition, playground);
@@ -1318,7 +1333,7 @@ crate fn markdown_links(md: &str) -> Vec<MarkdownLink> {
13181333
// There's no need to thread an IdMap through to here because
13191334
// the IDs generated aren't going to be emitted anywhere.
13201335
let mut ids = IdMap::new();
1321-
let iter = Footnotes::new(HeadingLinks::new(p, None, &mut ids, 0));
1336+
let iter = Footnotes::new(HeadingLinks::new(p, None, &mut ids, HeadingOffset::H1));
13221337

13231338
for ev in iter {
13241339
if let Event::Start(Tag::Link(kind, dest, _)) = ev.0 {

‎src/librustdoc/html/markdown/tests.rs

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
use super::{find_testable_code, plain_text_summary, short_markdown_summary};
2-
use super::{ErrorCodes, IdMap, Ignore, LangString, Markdown, MarkdownHtml};
2+
use super::{ErrorCodes, HeadingOffset, IdMap, Ignore, LangString, Markdown, MarkdownHtml};
33
use rustc_span::edition::{Edition, DEFAULT_EDITION};
44

55
#[test]
@@ -154,7 +154,7 @@ fn test_header() {
154154
error_codes: ErrorCodes::Yes,
155155
edition: DEFAULT_EDITION,
156156
playground: &None,
157-
heading_level: 1,
157+
heading_offset: HeadingOffset::H2,
158158
}
159159
.into_string();
160160
assert_eq!(output, expect, "original: {}", input);
@@ -196,7 +196,7 @@ fn test_header_ids_multiple_blocks() {
196196
error_codes: ErrorCodes::Yes,
197197
edition: DEFAULT_EDITION,
198198
playground: &None,
199-
heading_level: 1,
199+
heading_offset: HeadingOffset::H2,
200200
}
201201
.into_string();
202202
assert_eq!(output, expect, "original: {}", input);

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

+26-16
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ use crate::html::format::{
6767
href, print_abi_with_space, print_constness_with_space, print_default_space,
6868
print_generic_bounds, print_where_clause, Buffer, HrefError, PrintWithSpace,
6969
};
70-
use crate::html::markdown::{Markdown, MarkdownHtml, MarkdownSummaryLine};
70+
use crate::html::markdown::{HeadingOffset, Markdown, MarkdownHtml, MarkdownSummaryLine};
7171

7272
/// A pair of name and its optional document.
7373
crate type NameDoc = (String, Option<String>);
@@ -475,16 +475,16 @@ fn document(
475475
cx: &Context<'_>,
476476
item: &clean::Item,
477477
parent: Option<&clean::Item>,
478-
level: u32,
478+
heading_offset: HeadingOffset,
479479
) {
480480
if let Some(ref name) = item.name {
481481
info!("Documenting {}", name);
482482
}
483483
document_item_info(w, cx, item, parent);
484484
if parent.is_none() {
485-
document_full_collapsible(w, item, cx, level);
485+
document_full_collapsible(w, item, cx, heading_offset);
486486
} else {
487-
document_full(w, item, cx, level);
487+
document_full(w, item, cx, heading_offset);
488488
}
489489
}
490490

@@ -494,7 +494,7 @@ fn render_markdown(
494494
cx: &Context<'_>,
495495
md_text: &str,
496496
links: Vec<RenderedLink>,
497-
heading_level: u32,
497+
heading_offset: HeadingOffset,
498498
) {
499499
let mut ids = cx.id_map.borrow_mut();
500500
write!(
@@ -507,7 +507,7 @@ fn render_markdown(
507507
error_codes: cx.shared.codes,
508508
edition: cx.shared.edition(),
509509
playground: &cx.shared.playground,
510-
heading_level,
510+
heading_offset,
511511
}
512512
.into_string()
513513
)
@@ -544,20 +544,30 @@ fn document_short(
544544
}
545545
}
546546

547-
fn document_full_collapsible(w: &mut Buffer, item: &clean::Item, cx: &Context<'_>, level: u32) {
548-
document_full_inner(w, item, cx, true, level);
547+
fn document_full_collapsible(
548+
w: &mut Buffer,
549+
item: &clean::Item,
550+
cx: &Context<'_>,
551+
heading_offset: HeadingOffset,
552+
) {
553+
document_full_inner(w, item, cx, true, heading_offset);
549554
}
550555

551-
fn document_full(w: &mut Buffer, item: &clean::Item, cx: &Context<'_>, level: u32) {
552-
document_full_inner(w, item, cx, false, level);
556+
fn document_full(
557+
w: &mut Buffer,
558+
item: &clean::Item,
559+
cx: &Context<'_>,
560+
heading_offset: HeadingOffset,
561+
) {
562+
document_full_inner(w, item, cx, false, heading_offset);
553563
}
554564

555565
fn document_full_inner(
556566
w: &mut Buffer,
557567
item: &clean::Item,
558568
cx: &Context<'_>,
559569
is_collapsible: bool,
560-
level: u32,
570+
heading_offset: HeadingOffset,
561571
) {
562572
if let Some(s) = cx.shared.maybe_collapsed_doc_value(item) {
563573
debug!("Doc block: =====\n{}\n=====", s);
@@ -568,10 +578,10 @@ fn document_full_inner(
568578
<span>Expand description</span>\
569579
</summary>",
570580
);
571-
render_markdown(w, cx, &s, item.links(cx), level);
581+
render_markdown(w, cx, &s, item.links(cx), heading_offset);
572582
w.write_str("</details>");
573583
} else {
574-
render_markdown(w, cx, &s, item.links(cx), level);
584+
render_markdown(w, cx, &s, item.links(cx), heading_offset);
575585
}
576586
}
577587
}
@@ -1340,7 +1350,7 @@ fn render_impl(
13401350
// because impls can't have a stability.
13411351
if item.doc_value().is_some() {
13421352
document_item_info(&mut info_buffer, cx, it, Some(parent));
1343-
document_full(&mut doc_buffer, item, cx, 4);
1353+
document_full(&mut doc_buffer, item, cx, HeadingOffset::H5);
13441354
short_documented = false;
13451355
} else {
13461356
// In case the item isn't documented,
@@ -1358,7 +1368,7 @@ fn render_impl(
13581368
} else {
13591369
document_item_info(&mut info_buffer, cx, item, Some(parent));
13601370
if rendering_params.show_def_docs {
1361-
document_full(&mut doc_buffer, item, cx, 4);
1371+
document_full(&mut doc_buffer, item, cx, HeadingOffset::H5);
13621372
short_documented = false;
13631373
}
13641374
}
@@ -1599,7 +1609,7 @@ fn render_impl(
15991609
error_codes: cx.shared.codes,
16001610
edition: cx.shared.edition(),
16011611
playground: &cx.shared.playground,
1602-
heading_level: 1
1612+
heading_offset: HeadingOffset::H2
16031613
}
16041614
.into_string()
16051615
);

0 commit comments

Comments
 (0)