squiid/rust
1
0
Fork 0
Code Issues Pull requests Projects Activity

heading_level: u32 -> heading_offset: HeadingOffset

Browse source
This commit is contained in:
Mukund Lakshman 2021-10-04 21:54:00 -04:00
parent 13558ee0a0
commit f1425c7c3e
7 changed files with 88 additions and 61 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
src/librustdoc/externalfiles.rs
View file

@ -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()
);

41
src/librustdoc/html/markdown.rs
View file

@ -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<Playground>,
/// Offset at which we render headings.
/// E.g. if `heading_level: 1`, then `# something` renders an `<h2>` instead of `<h1>`
pub heading_level: u32,
/// E.g. if `heading_offset: HeadingOffset::H2`, then `# something` renders an `<h2>`.
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<SpannedEvent<'a>>,
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<Item = SpannedEvent<'a>>> 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!("</a></h{}>", 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<MarkdownLink> {
// 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 {

6
src/librustdoc/html/markdown/tests.rs
View file

@ -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);

42
src/librustdoc/html/render/mod.rs
View file

@ -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<String>);
@ -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<RenderedLink>,
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(
<span>Expand description</span>\
</summary>",
);
render_markdown(w, cx, &s, item.links(cx), level);
render_markdown(w, cx, &s, item.links(cx), heading_offset);
w.write_str("</details>");
} 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()
);

44
src/librustdoc/html/render/print_item.rs
View file

@ -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 = "<div class=\"item-table\">";
const ITEM_TABLE_CLOSE: &'static str = "</div>";
@ -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::<Vec<usize>>();
@ -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, "<details class=\"rustdoc-toggle\" open><summary>");
@ -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, "<span class=\"stab {stab}\"></span>", 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("</code>");
render_stability_since(w, variant, it, cx.tcx());
w.write_str("</div>");
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).

6
src/librustdoc/markdown.rs
View file

@ -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<P: AsRef<Path>>(
error_codes,
edition,
playground: &playground,
heading_level: 0,
heading_offset: HeadingOffset::H1,
}
.into_string()
};

4
src/tools/error_index_generator/main.rs
View file

@ -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<String>,
@ -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()
)?