From f1425c7c3e62b519354d1a178181a66dad943b4e Mon Sep 17 00:00:00 2001 From: Mukund Lakshman Date: Mon, 4 Oct 2021 21:54:00 -0400 Subject: [PATCH] heading_level: u32 -> heading_offset: HeadingOffset --- src/librustdoc/externalfiles.rs | 6 ++-- src/librustdoc/html/markdown.rs | 41 +++++++++++++++------- src/librustdoc/html/markdown/tests.rs | 6 ++-- src/librustdoc/html/render/mod.rs | 42 +++++++++++++--------- src/librustdoc/html/render/print_item.rs | 44 ++++++++++++------------ src/librustdoc/markdown.rs | 6 ++-- src/tools/error_index_generator/main.rs | 4 +-- 7 files changed, 88 insertions(+), 61 deletions(-) diff --git a/src/librustdoc/externalfiles.rs b/src/librustdoc/externalfiles.rs index cb5c9edcde5..302fc5a6777 100644 --- a/src/librustdoc/externalfiles.rs +++ b/src/librustdoc/externalfiles.rs @@ -1,4 +1,4 @@ -use crate::html::markdown::{ErrorCodes, IdMap, Markdown, Playground}; +use crate::html::markdown::{ErrorCodes, HeadingOffset, IdMap, Markdown, Playground}; use crate::rustc_span::edition::Edition; use std::fs; use std::path::Path; @@ -46,7 +46,7 @@ impl ExternalHtml { error_codes: codes, edition, playground, - heading_level: 1 + heading_offset: HeadingOffset::H2, } .into_string() ); @@ -62,7 +62,7 @@ impl ExternalHtml { error_codes: codes, edition, playground, - heading_level: 1 + heading_offset: HeadingOffset::H2, } .into_string() ); diff --git a/src/librustdoc/html/markdown.rs b/src/librustdoc/html/markdown.rs index ef2f2f90301..9f2e282fce1 100644 --- a/src/librustdoc/html/markdown.rs +++ b/src/librustdoc/html/markdown.rs @@ -8,7 +8,7 @@ //! extern crate rustc_span; //! //! use rustc_span::edition::Edition; -//! use rustdoc::html::markdown::{IdMap, Markdown, ErrorCodes}; +//! use rustdoc::html::markdown::{HeadingOffset, IdMap, Markdown, ErrorCodes}; //! //! let s = "My *markdown* _text_"; //! let mut id_map = IdMap::new(); @@ -19,7 +19,7 @@ //! error_codes: ErrorCodes::Yes, //! edition: Edition::Edition2015, //! playground: &None, -//! heading_level: 1 +//! heading_offset: HeadingOffset::H2, //! }; //! let html = md.into_string(); //! // ... something using html @@ -75,6 +75,16 @@ pub(crate) fn summary_opts() -> Options { | Options::ENABLE_SMART_PUNCTUATION } +#[derive(Debug, Clone, Copy)] +pub enum HeadingOffset { + H1 = 0, + H2, + H3, + H4, + H5, + H6, +} + /// When `to_string` is called, this struct will emit the HTML corresponding to /// the rendered version of the contained markdown string. pub struct Markdown<'a> { @@ -89,8 +99,8 @@ pub struct Markdown<'a> { pub edition: Edition, pub playground: &'a Option, /// Offset at which we render headings. - /// E.g. if `heading_level: 1`, then `# something` renders an `

` instead of `

` - pub heading_level: u32, + /// E.g. if `heading_offset: HeadingOffset::H2`, then `# something` renders an `

`. + pub heading_offset: HeadingOffset, } /// A tuple struct like `Markdown` that renders the markdown with a table of contents. crate struct MarkdownWithToc<'a>( @@ -502,12 +512,17 @@ struct HeadingLinks<'a, 'b, 'ids, I> { toc: Option<&'b mut TocBuilder>, buf: VecDeque>, id_map: &'ids mut IdMap, - level: u32, + heading_offset: HeadingOffset, } impl<'a, 'b, 'ids, I> HeadingLinks<'a, 'b, 'ids, I> { - fn new(iter: I, toc: Option<&'b mut TocBuilder>, ids: &'ids mut IdMap, level: u32) -> Self { - HeadingLinks { inner: iter, toc, buf: VecDeque::new(), id_map: ids, level } + fn new( + iter: I, + toc: Option<&'b mut TocBuilder>, + ids: &'ids mut IdMap, + heading_offset: HeadingOffset, + ) -> Self { + HeadingLinks { inner: iter, toc, buf: VecDeque::new(), id_map: ids, heading_offset } } } @@ -544,7 +559,7 @@ impl<'a, 'b, 'ids, I: Iterator>> Iterator self.buf.push_front((Event::Html(format!("{} ", sec).into()), 0..0)); } - let level = std::cmp::min(level + self.level, MAX_HEADER_LEVEL); + let level = std::cmp::min(level + (self.heading_offset as u32), MAX_HEADER_LEVEL); self.buf.push_back((Event::Html(format!("", level).into()), 0..0)); let start_tags = format!( @@ -1027,7 +1042,7 @@ impl Markdown<'_> { error_codes: codes, edition, playground, - heading_level, + heading_offset, } = self; // This is actually common enough to special-case @@ -1049,7 +1064,7 @@ impl Markdown<'_> { let mut s = String::with_capacity(md.len() * 3 / 2); - let p = HeadingLinks::new(p, None, &mut ids, heading_level); + let p = HeadingLinks::new(p, None, &mut ids, heading_offset); let p = Footnotes::new(p); let p = LinkReplacer::new(p.map(|(ev, _)| ev), links); let p = TableWrapper::new(p); @@ -1071,7 +1086,7 @@ impl MarkdownWithToc<'_> { let mut toc = TocBuilder::new(); { - let p = HeadingLinks::new(p, Some(&mut toc), &mut ids, 0); + let p = HeadingLinks::new(p, Some(&mut toc), &mut ids, HeadingOffset::H1); let p = Footnotes::new(p); let p = TableWrapper::new(p.map(|(ev, _)| ev)); let p = CodeBlocks::new(p, codes, edition, playground); @@ -1100,7 +1115,7 @@ impl MarkdownHtml<'_> { let mut s = String::with_capacity(md.len() * 3 / 2); - let p = HeadingLinks::new(p, None, &mut ids, 0); + let p = HeadingLinks::new(p, None, &mut ids, HeadingOffset::H1); let p = Footnotes::new(p); let p = TableWrapper::new(p.map(|(ev, _)| ev)); let p = CodeBlocks::new(p, codes, edition, playground); @@ -1318,7 +1333,7 @@ crate fn markdown_links(md: &str) -> Vec { // There's no need to thread an IdMap through to here because // the IDs generated aren't going to be emitted anywhere. let mut ids = IdMap::new(); - let iter = Footnotes::new(HeadingLinks::new(p, None, &mut ids, 0)); + let iter = Footnotes::new(HeadingLinks::new(p, None, &mut ids, HeadingOffset::H1)); for ev in iter { if let Event::Start(Tag::Link(kind, dest, _)) = ev.0 { diff --git a/src/librustdoc/html/markdown/tests.rs b/src/librustdoc/html/markdown/tests.rs index ee6a1997896..68ab002f138 100644 --- a/src/librustdoc/html/markdown/tests.rs +++ b/src/librustdoc/html/markdown/tests.rs @@ -1,5 +1,5 @@ use super::{find_testable_code, plain_text_summary, short_markdown_summary}; -use super::{ErrorCodes, IdMap, Ignore, LangString, Markdown, MarkdownHtml}; +use super::{ErrorCodes, HeadingOffset, IdMap, Ignore, LangString, Markdown, MarkdownHtml}; use rustc_span::edition::{Edition, DEFAULT_EDITION}; #[test] @@ -154,7 +154,7 @@ fn test_header() { error_codes: ErrorCodes::Yes, edition: DEFAULT_EDITION, playground: &None, - heading_level: 1, + heading_offset: HeadingOffset::H2, } .into_string(); assert_eq!(output, expect, "original: {}", input); @@ -196,7 +196,7 @@ fn test_header_ids_multiple_blocks() { error_codes: ErrorCodes::Yes, edition: DEFAULT_EDITION, playground: &None, - heading_level: 1, + heading_offset: HeadingOffset::H2, } .into_string(); assert_eq!(output, expect, "original: {}", input); diff --git a/src/librustdoc/html/render/mod.rs b/src/librustdoc/html/render/mod.rs index 8cf11e526fe..11682afdf89 100644 --- a/src/librustdoc/html/render/mod.rs +++ b/src/librustdoc/html/render/mod.rs @@ -67,7 +67,7 @@ use crate::html::format::{ href, print_abi_with_space, print_constness_with_space, print_default_space, print_generic_bounds, print_where_clause, Buffer, HrefError, PrintWithSpace, }; -use crate::html::markdown::{Markdown, MarkdownHtml, MarkdownSummaryLine}; +use crate::html::markdown::{HeadingOffset, Markdown, MarkdownHtml, MarkdownSummaryLine}; /// A pair of name and its optional document. crate type NameDoc = (String, Option); @@ -475,16 +475,16 @@ fn document( cx: &Context<'_>, item: &clean::Item, parent: Option<&clean::Item>, - level: u32, + heading_offset: HeadingOffset, ) { if let Some(ref name) = item.name { info!("Documenting {}", name); } document_item_info(w, cx, item, parent); if parent.is_none() { - document_full_collapsible(w, item, cx, level); + document_full_collapsible(w, item, cx, heading_offset); } else { - document_full(w, item, cx, level); + document_full(w, item, cx, heading_offset); } } @@ -494,7 +494,7 @@ fn render_markdown( cx: &Context<'_>, md_text: &str, links: Vec, - heading_level: u32, + heading_offset: HeadingOffset, ) { let mut ids = cx.id_map.borrow_mut(); write!( @@ -507,7 +507,7 @@ fn render_markdown( error_codes: cx.shared.codes, edition: cx.shared.edition(), playground: &cx.shared.playground, - heading_level, + heading_offset, } .into_string() ) @@ -544,12 +544,22 @@ fn document_short( } } -fn document_full_collapsible(w: &mut Buffer, item: &clean::Item, cx: &Context<'_>, level: u32) { - document_full_inner(w, item, cx, true, level); +fn document_full_collapsible( + w: &mut Buffer, + item: &clean::Item, + cx: &Context<'_>, + heading_offset: HeadingOffset, +) { + document_full_inner(w, item, cx, true, heading_offset); } -fn document_full(w: &mut Buffer, item: &clean::Item, cx: &Context<'_>, level: u32) { - document_full_inner(w, item, cx, false, level); +fn document_full( + w: &mut Buffer, + item: &clean::Item, + cx: &Context<'_>, + heading_offset: HeadingOffset, +) { + document_full_inner(w, item, cx, false, heading_offset); } fn document_full_inner( @@ -557,7 +567,7 @@ fn document_full_inner( item: &clean::Item, cx: &Context<'_>, is_collapsible: bool, - level: u32, + heading_offset: HeadingOffset, ) { if let Some(s) = cx.shared.maybe_collapsed_doc_value(item) { debug!("Doc block: =====\n{}\n=====", s); @@ -568,10 +578,10 @@ fn document_full_inner( Expand description\ ", ); - render_markdown(w, cx, &s, item.links(cx), level); + render_markdown(w, cx, &s, item.links(cx), heading_offset); w.write_str(""); } else { - render_markdown(w, cx, &s, item.links(cx), level); + render_markdown(w, cx, &s, item.links(cx), heading_offset); } } } @@ -1340,7 +1350,7 @@ fn render_impl( // because impls can't have a stability. if item.doc_value().is_some() { document_item_info(&mut info_buffer, cx, it, Some(parent)); - document_full(&mut doc_buffer, item, cx, 4); + document_full(&mut doc_buffer, item, cx, HeadingOffset::H5); short_documented = false; } else { // In case the item isn't documented, @@ -1358,7 +1368,7 @@ fn render_impl( } else { document_item_info(&mut info_buffer, cx, item, Some(parent)); if rendering_params.show_def_docs { - document_full(&mut doc_buffer, item, cx, 4); + document_full(&mut doc_buffer, item, cx, HeadingOffset::H5); short_documented = false; } } @@ -1599,7 +1609,7 @@ fn render_impl( error_codes: cx.shared.codes, edition: cx.shared.edition(), playground: &cx.shared.playground, - heading_level: 1 + heading_offset: HeadingOffset::H2 } .into_string() ); diff --git a/src/librustdoc/html/render/print_item.rs b/src/librustdoc/html/render/print_item.rs index f26ee84569b..9b39a3eeaf0 100644 --- a/src/librustdoc/html/render/print_item.rs +++ b/src/librustdoc/html/render/print_item.rs @@ -30,7 +30,7 @@ use crate::html::format::{ }; use crate::html::highlight; use crate::html::layout::Page; -use crate::html::markdown::MarkdownSummaryLine; +use crate::html::markdown::{HeadingOffset, MarkdownSummaryLine}; const ITEM_TABLE_OPEN: &'static str = "
"; const ITEM_TABLE_CLOSE: &'static str = "
"; @@ -173,7 +173,7 @@ fn toggle_close(w: &mut Buffer) { } fn item_module(w: &mut Buffer, cx: &Context<'_>, item: &clean::Item, items: &[clean::Item]) { - document(w, cx, item, None, 1); + document(w, cx, item, None, HeadingOffset::H2); let mut indices = (0..items.len()).filter(|i| !items[*i].is_stripped()).collect::>(); @@ -485,7 +485,7 @@ fn item_function(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, f: &clean:: notable_traits = notable_traits_decl(&f.decl, cx), ); }); - document(w, cx, it, None, 1) + document(w, cx, it, None, HeadingOffset::H2) } fn item_trait(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, t: &clean::Trait) { @@ -608,7 +608,7 @@ fn item_trait(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, t: &clean::Tra }); // Trait documentation - document(w, cx, it, None, 1); + document(w, cx, it, None, HeadingOffset::H2); fn write_small_section_header(w: &mut Buffer, id: &str, title: &str, extra_content: &str) { write!( @@ -626,7 +626,7 @@ fn item_trait(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, t: &clean::Tra let item_type = m.type_(); let id = cx.derive_id(format!("{}.{}", item_type, name)); let mut content = Buffer::empty_from(w); - document(&mut content, cx, m, Some(t), 4); + document(&mut content, cx, m, Some(t), HeadingOffset::H5); let toggled = !content.is_empty(); if toggled { write!(w, "
"); @@ -840,7 +840,7 @@ fn item_trait_alias(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, t: &clea ); }); - document(w, cx, it, None, 1); + document(w, cx, it, None, HeadingOffset::H2); // Render any items associated directly to this alias, as otherwise they // won't be visible anywhere in the docs. It would be nice to also show @@ -862,7 +862,7 @@ fn item_opaque_ty(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, t: &clean: ); }); - document(w, cx, it, None, 1); + document(w, cx, it, None, HeadingOffset::H2); // Render any items associated directly to this alias, as otherwise they // won't be visible anywhere in the docs. It would be nice to also show @@ -893,7 +893,7 @@ fn item_typedef( ); }); - document(w, cx, it, None, 1); + document(w, cx, it, None, HeadingOffset::H2); let def_id = it.def_id.expect_def_id(); // Render any items associated directly to this alias, as otherwise they @@ -911,7 +911,7 @@ fn item_union(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, s: &clean::Uni }); }); - document(w, cx, it, None, 1); + document(w, cx, it, None, HeadingOffset::H2); let mut fields = s .fields @@ -944,7 +944,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), 1); + document(w, cx, field, Some(it), HeadingOffset::H2); } } let def_id = it.def_id.expect_def_id(); @@ -1026,7 +1026,7 @@ fn item_enum(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, e: &clean::Enum }); }); - document(w, cx, it, None, 1); + document(w, cx, it, None, HeadingOffset::H2); if !e.variants.is_empty() { write!( @@ -1055,7 +1055,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), 1); + document(w, cx, variant, Some(it), HeadingOffset::H2); document_non_exhaustive(w, variant); use crate::clean::Variant; @@ -1095,7 +1095,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), 1); + document(w, cx, field, Some(variant), HeadingOffset::H2); } _ => unreachable!(), } @@ -1122,7 +1122,7 @@ fn item_macro(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, t: &clean::Mac None, ); }); - document(w, cx, it, None, 1) + document(w, cx, it, None, HeadingOffset::H2) } fn item_proc_macro(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, m: &clean::ProcMacro) { @@ -1152,11 +1152,11 @@ fn item_proc_macro(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, m: &clean }); } } - document(w, cx, it, None, 1) + document(w, cx, it, None, HeadingOffset::H2) } fn item_primitive(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item) { - document(w, cx, it, None, 1); + document(w, cx, it, None, HeadingOffset::H2); render_assoc_items(w, cx, it, it.def_id.expect_def_id(), AssocItemRender::All) } @@ -1195,7 +1195,7 @@ fn item_constant(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, c: &clean:: } }); - document(w, cx, it, None, 1) + document(w, cx, it, None, HeadingOffset::H2) } fn item_struct(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, s: &clean::Struct) { @@ -1206,7 +1206,7 @@ fn item_struct(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, s: &clean::St }); }); - document(w, cx, it, None, 1); + document(w, cx, it, None, HeadingOffset::H2); let mut fields = s .fields @@ -1242,7 +1242,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), 1); + document(w, cx, field, Some(it), HeadingOffset::H2); } } } @@ -1263,7 +1263,7 @@ fn item_static(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item, s: &clean::St typ = s.type_.print(cx) ); }); - document(w, cx, it, None, 1) + document(w, cx, it, None, HeadingOffset::H2) } fn item_foreign_type(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item) { @@ -1278,13 +1278,13 @@ fn item_foreign_type(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item) { ); }); - document(w, cx, it, None, 1); + document(w, cx, it, None, HeadingOffset::H2); render_assoc_items(w, cx, it, it.def_id.expect_def_id(), AssocItemRender::All) } fn item_keyword(w: &mut Buffer, cx: &Context<'_>, it: &clean::Item) { - document(w, cx, it, None, 1) + document(w, cx, it, None, HeadingOffset::H2) } /// Compare two strings treating multi-digit numbers as single units (i.e. natural sort order). diff --git a/src/librustdoc/markdown.rs b/src/librustdoc/markdown.rs index 962712f5b91..47b24d40edc 100644 --- a/src/librustdoc/markdown.rs +++ b/src/librustdoc/markdown.rs @@ -10,7 +10,9 @@ use crate::config::{Options, RenderOptions}; use crate::doctest::{Collector, TestOptions}; use crate::html::escape::Escape; use crate::html::markdown; -use crate::html::markdown::{find_testable_code, ErrorCodes, IdMap, Markdown, MarkdownWithToc}; +use crate::html::markdown::{ + find_testable_code, ErrorCodes, HeadingOffset, IdMap, Markdown, MarkdownWithToc, +}; /// Separate any lines at the start of the file that begin with `# ` or `%`. fn extract_leading_metadata(s: &str) -> (Vec<&str>, &str) { @@ -77,7 +79,7 @@ crate fn render>( error_codes, edition, playground: &playground, - heading_level: 0, + heading_offset: HeadingOffset::H1, } .into_string() }; diff --git a/src/tools/error_index_generator/main.rs b/src/tools/error_index_generator/main.rs index f89f28242a2..e7969349610 100644 --- a/src/tools/error_index_generator/main.rs +++ b/src/tools/error_index_generator/main.rs @@ -14,7 +14,7 @@ use std::path::PathBuf; use rustc_span::edition::DEFAULT_EDITION; -use rustdoc::html::markdown::{ErrorCodes, IdMap, Markdown, Playground}; +use rustdoc::html::markdown::{ErrorCodes, HeadingOffset, IdMap, Markdown, Playground}; pub struct ErrorMetadata { pub description: Option, @@ -126,7 +126,7 @@ impl Formatter for HTMLFormatter { error_codes: ErrorCodes::Yes, edition: DEFAULT_EDITION, playground: &Some(playground), - heading_level: 1 + heading_offset: HeadingOffset::H2, } .into_string() )?