Auto merge of #41991 - GuillaumeGomez:rustdoc-html-diff, r=nrc

Add warnings when rustdoc html rendering differs

Author: bors

src/Cargo.lock

@@ -12,6 +12,7 @@ path = "lib.rs"
 env_logger = { version = "0.4", default-features = false }
 log = "0.3"
 pulldown-cmark = { version = "0.0.14", default-features = false }
+html-diff = "0.0.3"
 
 [build-dependencies]
 build_helper = { path = "../build_helper" }

src/librustdoc/Cargo.toml

@@ -75,6 +75,8 @@ use html::item_type::ItemType;
 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>);
 
@@ -1643,6 +1645,33 @@ fn document(w: &mut fmt::Formatter, cx: &Context, item: &clean::Item) -> fmt::Re
  Ok(())
 }
 
+fn get_html_diff(w: &mut fmt::Formatter, md_text: &str, render_type: RenderType,
+ prefix: &str) -> fmt::Result {
+ let output = format!("{}", Markdown(md_text, render_type));
+ let old = format!("{}", Markdown(md_text, match render_type {
+ RenderType::Hoedown => RenderType::Pulldown,
+ RenderType::Pulldown => RenderType::Hoedown,
+ }));
+ let differences = html_diff::get_differences(&output, &old);
+ if !differences.is_empty() {
+ println!("Differences spotted in {:?}:\n{}",
+ md_text,
+ differences.iter()
+ .filter_map(|s| {
+ match *s {
+ html_diff::Difference::NodeText { ref elem_text,
+ ref opposite_elem_text,
+ .. }
+ if elem_text.trim() == opposite_elem_text.trim() => None,
+ _ => Some(format!("=> {}", s.to_string())),
+ }
+ })
+ .collect::<Vec<String>>()
+ .join("\n"));
+ }
+ write!(w, "<div class='docblock'>{}{}</div>", prefix, output)
+}
+
 fn document_short(w: &mut fmt::Formatter, item: &clean::Item, link: AssocItemLink,
  render_type: RenderType, prefix: &str) -> fmt::Result {
  if let Some(s) = item.doc_value() {
@@ -1652,7 +1681,7 @@ fn document_short(w: &mut fmt::Formatter, item: &clean::Item, link: AssocItemLin
  } else {
  format!("{}", &plain_summary_line(Some(s)))
  };
- write!(w, "<div class='docblock'>{}{}</div>", prefix, Markdown(&markdown, render_type))?;
+ get_html_diff(w, &markdown, render_type, prefix)?;
  } else if !prefix.is_empty() {
  write!(w, "<div class='docblock'>{}</div>", prefix)?;
  }
@@ -1676,7 +1705,7 @@ fn render_assoc_const_value(item: &clean::Item) -> String {
 fn document_full(w: &mut fmt::Formatter, item: &clean::Item,
  render_type: RenderType, prefix: &str) -> fmt::Result {
  if let Some(s) = item.doc_value() {
- write!(w, "<div class='docblock'>{}{}</div>", prefix, Markdown(s, render_type))?;
+ get_html_diff(w, s, render_type, prefix)?;
  } else if !prefix.is_empty() {
  write!(w, "<div class='docblock'>{}</div>", prefix)?;
  }

src/librustdoc/html/render.rs

@@ -28,6 +28,7 @@
 extern crate arena;
 extern crate getopts;
 extern crate env_logger;
+extern crate html_diff;
 extern crate libc;
 extern crate rustc;
 extern crate rustc_data_structures;

src/librustdoc/lib.rs

@@ -212,7 +212,7 @@
 //! # }
 //! ```
 //!
-//! [functions-list]: #functions-1
+//! [functions-list]: #functions-2
 //!
 //! ## io::Result
 //!

src/libstd/io/mod.rs

@@ -1,35 +1,2 @@
--include ../tools.mk
-
-# This is a whitelist of files which are stable crates or simply are not crates,
-# we don't check for the instability of these crates as they're all stable!
-STABLE_CRATES := \
-std \
-core \
-proc_macro \
-rsbegin.o \
-rsend.o \
-dllcrt2.o \
-crt2.o \
-clang_rt.%_dynamic.dylib
-
-# Generate a list of all crates in the sysroot. To do this we list all files in
-# rustc's sysroot, look at the filename, strip everything after the `-`, and
-# strip the leading `lib` (if present)
-SYSROOT := $(shell $(RUSTC) --print sysroot)
-LIBS := $(wildcard $(SYSROOT)/lib/rustlib/$(TARGET)/lib/*)
-LIBS := $(foreach lib,$(LIBS),$(notdir $(lib)))
-LIBS := $(foreach lib,$(LIBS),$(word 1,$(subst -, ,$(lib))))
-LIBS := $(foreach lib,$(LIBS),$(patsubst lib%,%,$(lib)))
-LIBS := $(filter-out $(STABLE_CRATES),$(LIBS))
-
-all: $(foreach lib,$(LIBS),check-crate-$(lib)-is-unstable)
-
-check-crate-%-is-unstable:
-@echo verifying $* is an unstable crate
-@echo 'extern crate $*;' | \
-$(RUSTC) - --crate-type rlib 2>&1 | cat > $(TMPDIR)/$*; \
-true
-@grep -q 'use of unstable library feature' $(TMPDIR)/$* || \
-(echo crate $* is not unstable && \
-cat $(TMPDIR)/$* && \
-false)
+all:
+python2.7 test.py

src/test/run-make/sysroot-crates-are-unstable/Makefile

@@ -0,0 +1,71 @@
+# Copyright 2015 The Rust Project Developers. See the COPYRIGHT
+# file at the top-level directory of this distribution and at
+# http://rust-lang.org/COPYRIGHT.
+#
+# Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+# http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+# <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+# option. This file may not be copied, modified, or distributed
+# except according to those terms.
+
+import sys
+import os
+from os import listdir
+from os.path import isfile, join
+from subprocess import PIPE, Popen
+
+
+# This is a whitelist of files which are stable crates or simply are not crates,
+# we don't check for the instability of these crates as they're all stable!
+STABLE_CRATES = ['std', 'core', 'proc_macro', 'rsbegin.o', 'rsend.o', 'dllcrt2.o', 'crt2.o',
+ 'clang_rt']
+
+
+def convert_to_string(s):
+ if s.__class__.__name__ == 'bytes':
+ return s.decode('utf-8')
+ return s
+
+
+def exec_command(command, to_input=None):
+ child = None
+ if to_input is None:
+ child = Popen(command, stdout=PIPE, stderr=PIPE)
+ else:
+ child = Popen(command, stdout=PIPE, stderr=PIPE, stdin=PIPE)
+ stdout, stderr = child.communicate(input=to_input)
+ return (convert_to_string(stdout), convert_to_string(stderr))
+
+
+def check_lib(lib):
+ if lib['name'] in STABLE_CRATES:
+ return True
+ print('verifying if {} is an unstable crate'.format(lib['name']))
+ stdout, stderr = exec_command([os.environ['RUSTC'], '-', '--crate-type', 'rlib',
+ '--extern', '{}={}'.format(lib['name'], lib['path'])],
+ to_input='extern crate {};'.format(lib['name']))
+ if not 'use of unstable library feature' in '{}{}'.format(stdout, stderr):
+ print('crate {} "{}" is not unstable'.format(lib['name'], lib['path']))
+ print('{}{}'.format(stdout, stderr))
+ print('')
+ return False
+ return True
+
+# Generate a list of all crates in the sysroot. To do this we list all files in
+# rustc's sysroot, look at the filename, strip everything after the `-`, and
+# strip the leading `lib` (if present)
+def get_all_libs(dir_path):
+ return [{ 'path': join(dir_path, f), 'name': f[3:].split('-')[0] }
+ for f in listdir(dir_path)
+ if isfile(join(dir_path, f)) and f.endswith('.rlib') and f not in STABLE_CRATES]
+
+
+sysroot = exec_command([os.environ['RUSTC'], '--print', 'sysroot'])[0].replace('\n', '')
+libs = get_all_libs(join(sysroot, 'lib/rustlib/{}/lib'.format(os.environ['TARGET'])))
+
+ret = 0
+for lib in libs:
+ if not check_lib(lib):
+ # We continue so users can see all the not unstable crates.
+ ret = 1
+sys.exit(ret)

src/test/run-make/sysroot-crates-are-unstable/test.py

@@ -18,12 +18,12 @@ impl Foo {
  /// # Panics
  pub fn bar() {}
 
- // @has - '//*[@id="examples-1"]//a' 'Examples'
+ // @has - '//*[@id="examples-2"]//a' 'Examples'
  /// # Examples
  pub fn bar_1() {}
 
- // @has - '//*[@id="examples-2"]//a' 'Examples'
- // @has - '//*[@id="panics-1"]//a' 'Panics'
+ // @has - '//*[@id="examples-4"]//a' 'Examples'
+ // @has - '//*[@id="panics-2"]//a' 'Panics'
  /// # Examples
  /// # Panics
  pub fn bar_2() {}

src/test/rustdoc/issue-29449.rs

@@ -33,6 +33,12 @@ static EXCEPTIONS: &'static [&'static str] = &[
  "openssl", // BSD+advertising clause, cargo, mdbook
  "pest", // MPL2, mdbook via handlebars
  "thread-id", // Apache-2.0, mdbook
+ "cssparser", // MPL-2.0, rustdoc
+ "smallvec", // MPL-2.0, rustdoc
+ "magenta-sys", // BSD-3-Clause, rustdoc
+ "magenta", // BSD-3-Clause, rustdoc
+ "cssparser-macros", // MPL-2.0, rustdoc
+ "selectors", // MPL-2.0, rustdoc
 ];
 
 pub fn check(path: &Path, bad: &mut bool) {