Improve the Pulldown/hoedown warnings #44238

nrc · 2017-09-01T03:37:24Z

cc #44229

r? @QuietMisdreavus

Also checks for differences after eliminating whitespace-only diffs. Renames get_html_diff

nrc · 2017-09-01T03:39:05Z

Sample output: https://gist.github.com/nrc/e4ba8c465a5174daa616361705bf14c1

c.f., old output: https://gist.github.com/nrc/bb73f63a2a87d29ed7e10609a81ceb64

QuietMisdreavus

Couple questions

QuietMisdreavus · 2017-09-01T03:43:45Z

src/librustdoc/html/render.rs

+    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.");


Do we want all these println!s to be on stdout or stderr?

I wanted them to be on stderr, but using eprintln gave no output - I'm not sure if Rustbuild or something else is swallowing stderr. I can try again to confirm I wasn't missing something, but I fear we may be stuck with stdout.

If that's the case i won't object. I'm not sure if rustdoc has printed anything that didn't come from a panic before now.

QuietMisdreavus · 2017-09-01T03:47:47Z

src/librustdoc/html/render.rs

+
+// A short, single-line view of `s`.
+fn concise_str(s: &str) -> String {
+    if s.contains('\n') {


From the rest of the diff, i'm assuming that the text fed to this function has always been run through one of the renderers. Can either of them use Windows line endings? Does it matter?

Good catch, I can adjust that.

Just using something like .lines().next() would catch it, i assume.

QuietMisdreavus · 2017-09-01T04:20:14Z

From conversation on IRC, it seems like stderr is getting swallowed somewhere along the line. Possibly worth investigating, but not now. r=me pending travis.

GuillaumeGomez · 2017-09-01T06:32:56Z

src/librustdoc/html/render.rs

+                   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.


I don't understand: you said you wanted warnings all the time and it was one of the reasons to delay the merge. Why this change?

The core team thought that we should have this off by default until we've investigated (and probably remedied) the false positives and also communicated that these warnings are going to happen, so as not to surprise users. Sorry, for the back and forth here - my bad for not checking with the core team before asking to turn on by default.

GuillaumeGomez · 2017-09-01T06:33:08Z

src/librustdoc/html/render.rs

    write!(w, "<div class='docblock'>{}{}</div>", prefix, output)
 }

+// Returns true iff s1 and s2 match, ignoring whitespace.


It's an abbreviation for 'if and only if'

This is just undoing changes from rust-lang#41991 because we are not running markdown rendering twice.

nrc · 2017-09-01T08:08:16Z

@bors: r=@QuietMisdreavus p=10

bors · 2017-09-01T08:08:17Z

📌 Commit 1d6d09f has been approved by @QuietMisdreavus

bors · 2017-09-01T08:46:21Z

⌛ Testing commit 1d6d09f with merge 54793738b28b1495d20de370b03381e0a0e3ceb4...

bors · 2017-09-01T09:56:10Z

💔 Test failed - status-travis

kennytm · 2017-09-01T13:34:06Z

@bors retry #44221.

[00:34:47]    Compiling rustc_save_analysis v0.0.0 (file:///Users/travis/build/rust-lang/rust/src/librustc_save_analysis)
[00:34:54]    Compiling rustc_borrowck v0.0.0 (file:///Users/travis/build/rust-lang/rust/src/librustc_borrowck)
No output has been received in the last 30m0s, this potentially indicates a stalled build or something wrong with the build itself.
Check the details on how to adjust your build configuration on: https://docs.travis-ci.com/user/common-build-problems/#Build-times-out-because-no-output-was-received
The build has been terminated

ollie27 · 2017-09-01T13:18:58Z

src/librustdoc/html/render.rs

+// 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 the first line is really long then this should probably only print the start of it like the case below.

ollie27 · 2017-09-01T13:19:41Z

src/librustdoc/html/render.rs

+        return format!("{}...", s.lines().next().expect("Impossible! We just found a newline"));
+    }
+    if s.len() > 70 {
+        return format!("{} ... {}", &s[..50], &s[s.len()-20..]);


This will panic if 50 or s.len()-20 isn't on a character boundary.

ollie27 · 2017-09-01T13:23:41Z

src/librustdoc/html/render.rs

+                    _ => true,
+                }
+            })
+            .collect::<Vec<_>>();


Vec::retain would be cleaner.

ollie27 · 2017-09-01T13:29:03Z

src/librustdoc/html/render.rs

+    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"));


Why would these be considered equal? match_non_whitespace is almost identical to s1.split_whitespace().eq(s2.split_whitespace()) except for the two cases above. However, the whitepace should be handled in html_diff anyway as whether it matters depends on the context. For example whitespace is very important inside <pre> tags.

bors · 2017-09-01T13:56:29Z

⌛ Testing commit 1d6d09f with merge ed532c0...

@QuietMisdreavus

Improve the Pulldown/hoedown warnings cc #44229 r? @QuietMisdreavus

bors · 2017-09-01T16:39:26Z

☀️ Test successful - status-appveyor, status-travis
Approved by: @QuietMisdreavus
Pushing ed532c0 to master...

@ollie27

Fixup some nits from rust-lang#44238 r? @ollie27

@ollie27

Fixup some nits from rust-lang#44238 r? @ollie27

@ollie27

Fixup some nits from rust-lang#44238 r? @ollie27

nrc added 4 commits September 1, 2017 11:22

Only emit warnings if the user is using Pulldown

a5f50a9

Also checks for differences after eliminating whitespace-only diffs. Renames get_html_diff

rustdoc: collect rendering warnings and print them in one place

9ab20a3

Improve the appearance of markdown warnings

1a8aac3

Do a better job of eliding whitespace-only differences from warnings

abc0530

rust-highfive assigned QuietMisdreavus Sep 1, 2017

QuietMisdreavus reviewed Sep 1, 2017

View reviewed changes

Windows line endings

fbb1612

GuillaumeGomez reviewed Sep 1, 2017

View reviewed changes

Fix tests

1d6d09f

This is just undoing changes from rust-lang#41991 because we are not running markdown rendering twice.

nrc force-pushed the pulldown-warn branch from 4cfbdc2 to 1d6d09f Compare September 1, 2017 08:07

ollie27 reviewed Sep 1, 2017

View reviewed changes

bors added a commit that referenced this pull request Sep 1, 2017

Auto merge of #44238 - nrc:pulldown-warn, r=@QuietMisdreavus

ed532c0

Improve the Pulldown/hoedown warnings cc #44229 r? @QuietMisdreavus

bors merged commit 1d6d09f into rust-lang:master Sep 1, 2017

bors mentioned this pull request Sep 1, 2017

rustdoc: add new "Implementations on Foreign Types" section to traits #43849

Merged

nrc mentioned this pull request Sep 5, 2017

Tracking issue (Rustdoc): hoedown -> pulldown migration #44229

Closed

10 tasks

nrc added a commit to nrc/rust that referenced this pull request Sep 5, 2017

Fixup some nits from rust-lang#44238

0573949

frewsxcv added a commit to frewsxcv/rust that referenced this pull request Sep 9, 2017

Rollup merge of rust-lang#44329 - nrc:pulldown-warn-fix, r=ollie27

0dcfab9

Fixup some nits from rust-lang#44238 r? @ollie27

frewsxcv added a commit to frewsxcv/rust that referenced this pull request Sep 9, 2017

Rollup merge of rust-lang#44329 - nrc:pulldown-warn-fix, r=ollie27

66becdc

Fixup some nits from rust-lang#44238 r? @ollie27

GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this pull request Sep 10, 2017

Rollup merge of rust-lang#44329 - nrc:pulldown-warn-fix, r=ollie27

078e1c5

Fixup some nits from rust-lang#44238 r? @ollie27

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve the Pulldown/hoedown warnings #44238

Improve the Pulldown/hoedown warnings #44238

nrc commented Sep 1, 2017 •

edited

Loading

nrc commented Sep 1, 2017

QuietMisdreavus left a comment

QuietMisdreavus Sep 1, 2017

nrc Sep 1, 2017

QuietMisdreavus Sep 1, 2017

QuietMisdreavus Sep 1, 2017

nrc Sep 1, 2017

QuietMisdreavus Sep 1, 2017

QuietMisdreavus commented Sep 1, 2017

GuillaumeGomez Sep 1, 2017

nrc Sep 1, 2017

GuillaumeGomez Sep 1, 2017

nrc Sep 1, 2017

nrc commented Sep 1, 2017

bors commented Sep 1, 2017

bors commented Sep 1, 2017

bors commented Sep 1, 2017

kennytm commented Sep 1, 2017

ollie27 Sep 1, 2017

ollie27 Sep 1, 2017

ollie27 Sep 1, 2017

ollie27 Sep 1, 2017

bors commented Sep 1, 2017

bors commented Sep 1, 2017

Improve the Pulldown/hoedown warnings #44238

Improve the Pulldown/hoedown warnings #44238

Conversation

nrc commented Sep 1, 2017 • edited Loading

nrc commented Sep 1, 2017

QuietMisdreavus left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

QuietMisdreavus commented Sep 1, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nrc commented Sep 1, 2017

bors commented Sep 1, 2017

bors commented Sep 1, 2017

bors commented Sep 1, 2017

kennytm commented Sep 1, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bors commented Sep 1, 2017

bors commented Sep 1, 2017

nrc commented Sep 1, 2017 •

edited

Loading