Added the mdbook-linkcheck backend #27

Michael-F-Bryan · 2018-01-27T06:33:18Z

Now mdbook 0.1.0 has been released and the mdbook-linkcheck tool is on crates.io we can use it for automatic link checking.

I also found two broken links from chapters which were copied form the original READMEs.

To use the mdbook-linkcheck tool you'll need to have it installed (cargo install mdbook-linkcheck). If it isn't installed, mdbook should warn you saying a backend wasn't found, but continue on anyway.

Because we're now using the linkchecker to validate every build, I've updated travis.yml to use mdbook build as the test script. This also removes the need for ci/github_pages.sh.

We don't need to cache pip or run pip install ghp_imports any more either because we're using the proper GitHub Pages deployment provider.

Hopefully a smaller cache and not needing to install a Python program will speed up builds even more 🙂

(fixes #20)

Michael-F-Bryan · 2018-01-27T06:58:42Z

Just before this gets merged we should probably blow away all the travis caches because travis now needs to use version 0.1.1 instead of 0.0.28 of mdbook.

Michael-F-Bryan · 2018-01-27T07:33:25Z

I just added a commit which introduces a broken link and it looks the linkchecker correctly fails the build.

Changes:

diff --git a/src/about-this-guide.md b/src/about-this-guide.md
index ea84017..837bf95 100644
--- a/src/about-this-guide.md
+++ b/src/about-this-guide.md
@@ -11,4 +11,6 @@ be found at [the GitHub repository]. If you find any mistakes in the
 guide, please file an issue about it -- or, even better, open a PR
 with a correction!
 
+[A non-existent link](foo.md)
+
 [the GitHub repository]: https://github.com/rust-lang-nursery/rustc-guide/

Travis Log:

...
$ mdbook build
2018-01-27 07:30:43 [INFO] (mdbook::book): Book building has started
2018-01-27 07:30:43 [INFO] (mdbook::book): Running the html backend
2018-01-27 07:30:43 [INFO] (mdbook::book): Running the linkcheck backend
2018-01-27 07:30:43 [INFO] (mdbook::renderer): Invoking the "linkcheck" renderer
There was 1 broken link:
about-this-guide.md#14: Found "foo.md", did you mean "foo.html"?
2018-01-27 07:30:43 [ERROR] (mdbook::renderer): Renderer exited with non-zero return code.
2018-01-27 07:30:43 [ERROR] (mdbook::utils): Error: Rendering failed
2018-01-27 07:30:43 [ERROR] (mdbook::utils): 	Caused By: The "linkcheck" renderer failed
The command "mdbook build" exited with 101.

Unless there's anything else you'd like to address, @nikomatsakis I think we're about ready to merge.

nikomatsakis

Looks great! Left one nit.

nikomatsakis · 2018-01-29T14:23:57Z

.travis.yml

@@ -1,14 +1,11 @@
 language: rust
 cache:
- pip


nice, I meant to purge these at some point...

nikomatsakis · 2018-01-29T14:24:16Z

README.md

+To help prevent accidentally introducing broken links, we use the
+`mdbook-linkcheck`. If installed on your machine `mdbook` will automatically
+invoke this link checker, otherwise it will emit a warning saying it couldn't
+be found.


what kind of links does this check? can it test https links too?

It reads the contents of the raw chapters then uses pulldown-cmark to find all the links on a page. Then if it's a link to another chapter we make sure that chapter exists, otherwise if its http(s) it'll try to GET the page using reqwests.

Fetching pages from the web is disabled by default because it can take a while when your book has lots of them. Therefore you need to set output.linkcheck.follow-web-links to true in your book.toml.

nikomatsakis · 2018-01-29T14:25:07Z

src/high-level-overview.md

@@ -139,3 +139,5 @@ take:


 The first thing you may wonder if 
+
+[query model]: https://github.com/rust-lang/rust/blob/master/src/librustc/ty/maps/README.md


actually, we should .. oh, maybe I didn't open that PR yet =)

I have a PR adding a chapter for this... I'll have to remember to patch this link. :)

I added the chapter: https://rust-lang-nursery.github.io/rustc-guide/query.html

nikomatsakis · 2018-01-29T14:25:44Z

src/ty.md

@@ -78,7 +78,7 @@ is in fact a simple type alias for a reference with `'tcx` lifetime:
 pub type Ty<'tcx> = &'tcx TyS<'tcx>;
 ```

-[the HIR]: ../hir/README.md
+[the HIR]: https://github.com/rust-lang/rust/blob/master/src/librustc/hir/README.md


I think we do have a HIR chapter, though... can we redirect to the HIR page instead?

Hmm... that link is showing up as a 404 for me. Has the PR for it landed yet?

Ah, looks like it's hir.html, not hir-lowering.html.

Oh yeah I renamed it =)

nikomatsakis

I updated the links.

nikomatsakis · 2018-01-31T16:36:32Z

rebased.

nikomatsakis · 2018-01-31T17:51:15Z

So how do I run the link checker? mdbook build doesn't seem to do anything for me, whether that be warnings or otherwise. I did cargo install mdbook-linkcheck

mark-i-m · 2018-01-31T18:42:39Z

Perhaps you need ~~cargo update~~ to update mdbook? For me it just worked:

$ mdbook build
2018-01-31 12:41:16 [INFO] (mdbook::book): Book building has started
2018-01-31 12:41:16 [INFO] (mdbook::book): Running the html backend
2018-01-31 12:41:16 [INFO] (mdbook::book): Running the linkcheck backend
2018-01-31 12:41:16 [INFO] (mdbook::renderer): Invoking the "linkcheck" renderer
There were 4 broken links:
macro-expansion.md#44: Found "./the-parser.md", did you mean "./the-parser.html"?
type-inference.md#32: Found "src/librustc/ty/README.md", did you mean "src/librustc/ty/README.html"?
type-inference.md#40: Found "src/librustc/ty/README.md", did you mean "src/librustc/ty/README.html"?
type-inference.md#108: Found "../traits/README.md", did you mean "../traits/README.html"?
2018-01-31 12:41:16 [ERROR] (mdbook::renderer): Renderer exited with non-zero return code.
2018-01-31 12:41:16 [ERROR] (mdbook::utils): Error: Rendering failed
2018-01-31 12:41:16 [ERROR] (mdbook::utils): 	Caused By: The "linkcheck" renderer failed

Are you sure your book.toml is not in a weird state?

EDIT: Lol, that's not what cargo update does 😛

nikomatsakis · 2018-01-31T19:05:16Z

Mr-Darcy. mdbook --version
mdbook v0.0.28

Do I need some other version?

mark-i-m · 2018-01-31T19:06:01Z

I think you need >= 0.1

nikomatsakis · 2018-01-31T19:14:34Z

OK, got it. Weird that cargo +nightly install -f mdbook didn't get the latest version.

nikomatsakis · 2018-01-31T19:14:48Z

r=me once travis is happy =)

Rustc dev guide sync

Michael-F-Bryan requested a review from nikomatsakis January 27, 2018 06:44

Michael-F-Bryan force-pushed the linkcheck branch from 99a3dd2 to a501c72 Compare January 27, 2018 07:33

nikomatsakis requested changes Jan 29, 2018

View reviewed changes

nikomatsakis approved these changes Jan 31, 2018

View reviewed changes

nikomatsakis force-pushed the linkcheck branch from 518a9c0 to 413c397 Compare January 31, 2018 16:36

Michael-F-Bryan and others added 8 commits January 31, 2018 14:13

Added the mdbook-linkcheck backend

d39ba39

Updated CI to install and use mdbook-linkcheck

8b47122

Removed ghp-import and run mdbook build unconditionally

acf36f8

Added a note about how to use mdbook-linkcheck

79052b4

Toned down the log verbosity

66d2008

update to link within the book

046dc79

Update link to hir

0cedd25

fix some broken links

04cee3e

nikomatsakis force-pushed the linkcheck branch from 413c397 to 04cee3e Compare January 31, 2018 19:14

nikomatsakis merged commit 18490f5 into rust-lang:master Jan 31, 2018

Michael-F-Bryan deleted the linkcheck branch February 1, 2018 03:22

Kobzol added a commit to Kobzol/rustc-dev-guide that referenced this pull request Jan 5, 2025

Merge pull request rust-lang#27 from Kobzol/rustc-dev-guide-sync

a57f7df

Rustc dev guide sync

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Added the mdbook-linkcheck backend #27

Added the mdbook-linkcheck backend #27

Michael-F-Bryan commented Jan 27, 2018 •

edited

Loading

Michael-F-Bryan commented Jan 27, 2018

Michael-F-Bryan commented Jan 27, 2018

nikomatsakis left a comment

nikomatsakis Jan 29, 2018

nikomatsakis Jan 29, 2018

Michael-F-Bryan Jan 29, 2018

nikomatsakis Jan 29, 2018

nikomatsakis Jan 31, 2018

nikomatsakis Jan 29, 2018

Michael-F-Bryan Jan 29, 2018

Michael-F-Bryan Jan 29, 2018

nikomatsakis Jan 31, 2018

nikomatsakis left a comment

nikomatsakis commented Jan 31, 2018

nikomatsakis commented Jan 31, 2018

mark-i-m commented Jan 31, 2018 •

edited

Loading

nikomatsakis commented Jan 31, 2018

mark-i-m commented Jan 31, 2018

nikomatsakis commented Jan 31, 2018

nikomatsakis commented Jan 31, 2018

		@@ -139,3 +139,5 @@ take:


		The first thing you may wonder if

		[query model]: https://github.com/rust-lang/rust/blob/master/src/librustc/ty/maps/README.md

Added the mdbook-linkcheck backend #27

Added the mdbook-linkcheck backend #27

Conversation

Michael-F-Bryan commented Jan 27, 2018 • edited Loading

Michael-F-Bryan commented Jan 27, 2018

Michael-F-Bryan commented Jan 27, 2018

nikomatsakis 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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nikomatsakis left a comment

Choose a reason for hiding this comment

nikomatsakis commented Jan 31, 2018

nikomatsakis commented Jan 31, 2018

mark-i-m commented Jan 31, 2018 • edited Loading

nikomatsakis commented Jan 31, 2018

mark-i-m commented Jan 31, 2018

nikomatsakis commented Jan 31, 2018

nikomatsakis commented Jan 31, 2018

Michael-F-Bryan commented Jan 27, 2018 •

edited

Loading

mark-i-m commented Jan 31, 2018 •

edited

Loading