use rustc::session::config::nightly_options::is_nightly_build;
use rustc_data_structures::flock;
-use clean::{self, AttributesExt, GetDefId, SelfTy, Mutability};
+use clean::{self, AttributesExt, GetDefId, SelfTy, Mutability, Span};
use doctree;
use fold::DocFolder;
use html::escape::Escape;
use html::markdown::{self, Markdown, MarkdownHtml, MarkdownSummaryLine, RenderType};
use html::{highlight, layout};
+use html_diff;
+
/// A pair of name and its optional document.
pub type NameDoc = (String, Option<String>);
/// The given user css file which allow to customize the generated
/// documentation theme.
pub css_file_extension: Option<PathBuf>,
+ /// Warnings for the user if rendering would differ using different markdown
+ /// parsers.
+ pub markdown_warnings: RefCell<Vec<(Span, String, Vec<html_diff::Difference>)>>,
}
/// Indicates where an external crate can be found.
None => PathBuf::new(),
};
let mut scx = SharedContext {
- src_root: src_root,
- passes: passes,
+ src_root,
+ passes,
include_sources: true,
local_sources: FxHashMap(),
issue_tracker_base_url: None,
krate: krate.name.clone(),
},
css_file_extension: css_file_extension.clone(),
+ markdown_warnings: RefCell::new(vec![]),
};
// If user passed in `--playground-url` arg, we fill in crate name here
krate = render_sources(&dst, &mut scx, krate)?;
let cx = Context {
current: Vec::new(),
- dst: dst,
+ dst,
render_redirect_pages: false,
shared: Arc::new(scx),
- render_type: render_type,
+ render_type,
};
// Crawl the crate to build various caches used for the output
let mut cache = Cache {
impls: FxHashMap(),
- external_paths: external_paths,
+ external_paths,
paths: FxHashMap(),
implementors: FxHashMap(),
stack: Vec::new(),
access_levels: krate.access_levels.clone(),
orphan_impl_items: Vec::new(),
traits: mem::replace(&mut krate.external_traits, FxHashMap()),
- deref_trait_did: deref_trait_did,
- deref_mut_trait_did: deref_mut_trait_did,
- owned_box_did: owned_box_did,
+ deref_trait_did,
+ deref_mut_trait_did,
+ owned_box_did,
typarams: external_typarams,
};
write_shared(&cx, &krate, &*cache, index)?;
+ let scx = cx.shared.clone();
+
// And finally render the whole crate's documentation
- cx.krate(krate)
+ let result = cx.krate(krate);
+
+ let markdown_warnings = scx.markdown_warnings.borrow();
+ if !markdown_warnings.is_empty() {
+ println!("WARNING: documentation for this crate may be rendered \
+ differently using the new Pulldown renderer.");
+ println!(" See https://github.com/rust-lang/rust/issues/44229 for details.");
+ for &(ref span, ref text, ref diffs) in &*markdown_warnings {
+ println!("WARNING: rendering difference in `{}`", concise_str(text));
+ println!(" --> {}:{}:{}", span.filename, span.loline, span.locol);
+ for d in diffs {
+ render_difference(d);
+ }
+ }
+ }
+
+ result
+}
+
+// A short, single-line view of `s`.
+fn concise_str(s: &str) -> String {
+ if s.contains('\n') {
+ return format!("{}...", s.lines().next().expect("Impossible! We just found a newline"));
+ }
+ if s.len() > 70 {
+ return format!("{} ... {}", &s[..50], &s[s.len()-20..]);
+ }
+ s.to_owned()
+}
+
+// Returns short versions of s1 and s2, starting from where the strings differ.
+fn concise_compared_strs(s1: &str, s2: &str) -> (String, String) {
+ let s1 = s1.trim();
+ let s2 = s2.trim();
+ if !s1.contains('\n') && !s2.contains('\n') && s1.len() <= 70 && s2.len() <= 70 {
+ return (s1.to_owned(), s2.to_owned());
+ }
+
+ let mut start_byte = 0;
+ for (c1, c2) in s1.chars().zip(s2.chars()) {
+ if c1 != c2 {
+ break;
+ }
+
+ start_byte += c1.len_utf8();
+ }
+
+ if start_byte == 0 {
+ return (concise_str(s1), concise_str(s2));
+ }
+
+ let s1 = &s1[start_byte..];
+ let s2 = &s2[start_byte..];
+ (format!("...{}", concise_str(s1)), format!("...{}", concise_str(s2)))
+}
+
+fn render_difference(diff: &html_diff::Difference) {
+ match *diff {
+ html_diff::Difference::NodeType { ref elem, ref opposite_elem } => {
+ println!(" {} Types differ: expected: `{}`, found: `{}`",
+ elem.path, elem.element_name, opposite_elem.element_name);
+ }
+ html_diff::Difference::NodeName { ref elem, ref opposite_elem } => {
+ println!(" {} Tags differ: expected: `{}`, found: `{}`",
+ elem.path, elem.element_name, opposite_elem.element_name);
+ }
+ html_diff::Difference::NodeAttributes { ref elem,
+ ref elem_attributes,
+ ref opposite_elem_attributes,
+ .. } => {
+ println!(" {} Attributes differ in `{}`: expected: `{:?}`, found: `{:?}`",
+ elem.path, elem.element_name, elem_attributes, opposite_elem_attributes);
+ }
+ html_diff::Difference::NodeText { ref elem, ref elem_text, ref opposite_elem_text, .. } => {
+ let (s1, s2) = concise_compared_strs(elem_text, opposite_elem_text);
+ println!(" {} Text differs:\n expected: `{}`\n found: `{}`",
+ elem.path, s1, s2);
+ }
+ html_diff::Difference::NotPresent { ref elem, ref opposite_elem } => {
+ if let Some(ref elem) = *elem {
+ println!(" {} One element is missing: expected: `{}`",
+ elem.path, elem.element_name);
+ } else if let Some(ref elem) = *opposite_elem {
+ if elem.element_name.is_empty() {
+ println!(" {} Unexpected element: `{}`",
+ elem.path, concise_str(&elem.element_content));
+ } else {
+ println!(" {} Unexpected element `{}`: found: `{}`",
+ elem.path, elem.element_name, concise_str(&elem.element_content));
+ }
+ }
+ }
+ }
}
/// Build the search index from the collected metadata
let dst = dst.join("src").join(&krate.name);
try_err!(fs::create_dir_all(&dst), &dst);
let mut folder = SourceCollector {
- dst: dst,
- scx: scx,
+ dst,
+ scx,
};
Ok(folder.fold_crate(krate))
}
name: s.to_string(),
path: path.join("::").to_string(),
desc: plain_summary_line(item.doc_value()),
- parent: parent,
+ parent,
parent_idx: None,
search_type: get_index_search_type(&item),
});
} else {
write!(fmt, "Module ")?;
},
- clean::FunctionItem(..) | clean::ForeignFunctionItem(..) =>
- write!(fmt, "Function ")?,
+ clean::FunctionItem(..) | clean::ForeignFunctionItem(..) => write!(fmt, "Function ")?,
clean::TraitItem(..) => write!(fmt, "Trait ")?,
clean::StructItem(..) => write!(fmt, "Struct ")?,
clean::UnionItem(..) => write!(fmt, "Union ")?,
clean::TypedefItem(..) => write!(fmt, "Type Definition ")?,
clean::MacroItem(..) => write!(fmt, "Macro ")?,
clean::PrimitiveItem(..) => write!(fmt, "Primitive Type ")?,
- clean::StaticItem(..) | clean::ForeignStaticItem(..) =>
- write!(fmt, "Static ")?,
+ clean::StaticItem(..) | clean::ForeignStaticItem(..) => write!(fmt, "Static ")?,
clean::ConstantItem(..) => write!(fmt, "Constant ")?,
_ => {
// We don't generate pages for any other type.
fn document(w: &mut fmt::Formatter, cx: &Context, item: &clean::Item) -> fmt::Result {
document_stability(w, cx, item)?;
let prefix = render_assoc_const_value(item);
- document_full(w, item, cx.render_type, &prefix)?;
+ document_full(w, item, cx, &prefix)?;
Ok(())
}
+/// Render md_text as markdown. Warns the user if there are difference in
+/// rendering between Pulldown and Hoedown.
+fn render_markdown(w: &mut fmt::Formatter,
+ md_text: &str,
+ span: Span,
+ render_type: RenderType,
+ prefix: &str,
+ scx: &SharedContext)
+ -> fmt::Result {
+ let hoedown_output = format!("{}", Markdown(md_text, RenderType::Hoedown));
+ // We only emit warnings if the user has opted-in to Pulldown rendering.
+ let output = if render_type == RenderType::Pulldown {
+ let pulldown_output = format!("{}", Markdown(md_text, RenderType::Pulldown));
+ let differences = html_diff::get_differences(&pulldown_output, &hoedown_output);
+ let differences = differences.into_iter()
+ .filter(|s| {
+ match *s {
+ html_diff::Difference::NodeText { ref elem_text,
+ ref opposite_elem_text,
+ .. }
+ if match_non_whitespace(elem_text, opposite_elem_text) => false,
+ _ => true,
+ }
+ })
+ .collect::<Vec<_>>();
+
+ if !differences.is_empty() {
+ scx.markdown_warnings.borrow_mut().push((span, md_text.to_owned(), differences));
+ }
+
+ pulldown_output
+ } else {
+ hoedown_output
+ };
+
+ write!(w, "<div class='docblock'>{}{}</div>", prefix, output)
+}
+
+// Returns true iff s1 and s2 match, ignoring whitespace.
+fn match_non_whitespace(s1: &str, s2: &str) -> bool {
+ let s1 = s1.trim();
+ let s2 = s2.trim();
+ let mut cs1 = s1.chars();
+ let mut cs2 = s2.chars();
+ while let Some(c1) = cs1.next() {
+ if c1.is_whitespace() {
+ continue;
+ }
+
+ loop {
+ if let Some(c2) = cs2.next() {
+ if !c2.is_whitespace() {
+ if c1 != c2 {
+ return false;
+ }
+ break;
+ }
+ } else {
+ return false;
+ }
+ }
+ }
+
+ while let Some(c2) = cs2.next() {
+ if !c2.is_whitespace() {
+ return false;
+ }
+ }
+
+ true
+}
+
fn document_short(w: &mut fmt::Formatter, item: &clean::Item, link: AssocItemLink,
- render_type: RenderType, prefix: &str) -> fmt::Result {
+ cx: &Context, prefix: &str) -> fmt::Result {
if let Some(s) = item.doc_value() {
let markdown = if s.contains('\n') {
format!("{} [Read more]({})",
} else {
format!("{}", &plain_summary_line(Some(s)))
};
- write!(w, "<div class='docblock'>{}{}</div>", prefix, Markdown(&markdown, render_type))?;
+ render_markdown(w, &markdown, item.source.clone(), cx.render_type, prefix, &cx.shared)?;
} else if !prefix.is_empty() {
write!(w, "<div class='docblock'>{}</div>", prefix)?;
}
}
fn document_full(w: &mut fmt::Formatter, item: &clean::Item,
- render_type: RenderType, prefix: &str) -> fmt::Result {
+ cx: &Context, prefix: &str) -> fmt::Result {
if let Some(s) = item.doc_value() {
- write!(w, "<div class='docblock'>{}{}</div>", prefix, Markdown(s, render_type))?;
+ render_markdown(w, s, item.source.clone(), cx.render_type, prefix, &cx.shared)?;
} else if !prefix.is_empty() {
write!(w, "<div class='docblock'>{}</div>", prefix)?;
}
}
indices.sort_by(|&i1, &i2| cmp(&items[i1], &items[i2], i1, i2));
+ // This call is to remove reexport duplicates in cases such as:
+ //
+ // ```
+ // pub mod foo {
+ // pub mod bar {
+ // pub trait Double { fn foo(); }
+ // }
+ // }
+ //
+ // pub use foo::bar::*;
+ // pub use foo::*;
+ // ```
+ //
+ // `Double` will appear twice in the generated docs.
+ //
+ // FIXME: This code is quite ugly and could be improved. Small issue: DefId
+ // can be identical even if the elements are different (mostly in imports).
+ // So in case this is an import, we keep everything by adding a "unique id"
+ // (which is the position in the vector).
+ indices.dedup_by_key(|i| (items[*i].def_id,
+ if items[*i].name.as_ref().is_some() {
+ Some(full_path(cx, &items[*i]).clone())
+ } else {
+ None
+ },
+ items[*i].type_(),
+ if items[*i].is_import() {
+ *i
+ } else {
+ 0
+ }));
debug!("{:?}", indices);
let mut curty = None;
where_clause = WhereClause { gens: &f.generics, indent: 0, end_newline: true },
decl = Method {
decl: &f.decl,
- name_len: name_len,
+ name_len,
indent: 0,
})?;
document(w, cx, it)
decl = Method {
decl: d,
name_len: head_len,
- indent: indent,
+ indent,
},
where_clause = WhereClause {
gens: g,
- indent: indent,
- end_newline: end_newline,
+ indent,
+ end_newline,
})
}
match item.inner {
fn render_impl(w: &mut fmt::Formatter, cx: &Context, i: &Impl, link: AssocItemLink,
render_mode: RenderMode, outer_version: Option<&str>) -> fmt::Result {
if render_mode == RenderMode::Normal {
- write!(w, "<h3 class='impl'><span class='in-band'><code>{}</code>", i.inner_impl())?;
+ let id = derive_id(match i.inner_impl().trait_ {
+ Some(ref t) => format!("impl-{}", Escape(&format!("{:#}", t))),
+ None => "impl".to_string(),
+ });
+ write!(w, "<h3 id='{}' class='impl'><span class='in-band'><code>{}</code>",
+ id, i.inner_impl())?;
+ write!(w, "<a href='#{}' class='anchor'></a>", id)?;
write!(w, "</span><span class='out-of-band'>")?;
let since = i.impl_item.stability.as_ref().map(|s| &s.since[..]);
if let Some(l) = (Item { item: &i.impl_item, cx: cx }).src_href() {
// because impls can't have a stability.
document_stability(w, cx, it)?;
if item.doc_value().is_some() {
- document_full(w, item, cx.render_type, &prefix)?;
+ document_full(w, item, cx, &prefix)?;
} else {
// In case the item isn't documented,
// provide short documentation from the trait.
- document_short(w, it, link, cx.render_type, &prefix)?;
+ document_short(w, it, link, cx, &prefix)?;
}
}
} else {
document_stability(w, cx, item)?;
- document_full(w, item, cx.render_type, &prefix)?;
+ document_full(w, item, cx, &prefix)?;
}
} else {
document_stability(w, cx, item)?;
- document_short(w, item, link, cx.render_type, &prefix)?;
+ document_short(w, item, link, cx, &prefix)?;
}
}
Ok(())
sorted.sort_by_key(|&s| name_key(s));
assert_eq!(names, sorted);
}
+
+#[cfg(test)]
+#[test]
+fn test_match_non_whitespace() {
+ assert!(match_non_whitespace("", ""));
+ assert!(match_non_whitespace(" ", ""));
+ assert!(match_non_whitespace("", " "));
+
+ assert!(match_non_whitespace("a", "a"));
+ assert!(match_non_whitespace(" a ", "a"));
+ assert!(match_non_whitespace("a", " a"));
+ assert!(match_non_whitespace("abc", "abc"));
+ assert!(match_non_whitespace("abc", " abc "));
+ assert!(match_non_whitespace("abc ", "abc"));
+ assert!(match_non_whitespace("abc xyz", "abc xyz"));
+ assert!(match_non_whitespace("abc xyz", "abc\nxyz"));
+ assert!(match_non_whitespace("abc xyz", "abcxyz"));
+ assert!(match_non_whitespace("abcxyz", "abc xyz"));
+ assert!(match_non_whitespace("abc xyz ", " abc xyz\n"));
+
+ assert!(!match_non_whitespace("a", "b"));
+ assert!(!match_non_whitespace(" a ", "c"));
+ assert!(!match_non_whitespace("a", " aa"));
+ assert!(!match_non_whitespace("abc", "ac"));
+ assert!(!match_non_whitespace("abc", " adc "));
+ assert!(!match_non_whitespace("abc ", "abca"));
+ assert!(!match_non_whitespace("abc xyz", "abc xy"));
+ assert!(!match_non_whitespace("abc xyz", "bc\nxyz"));
+ assert!(!match_non_whitespace("abc xyz", "abc.xyz"));
+ assert!(!match_non_whitespace("abcxyz", "abc.xyz"));
+ assert!(!match_non_whitespace("abc xyz ", " abc xyz w"));
+}