Auto merge of #33092 - alexcrichton:rustbuild-docs, r=brson

rustbuild: Run all markdown documentation tests

This commit adds support to rustbuild to run all documentation tests, basically
running `rustdoc --test` over all our documentation.

Author: bors

src/bootstrap/build/check.rs

@@ -9,7 +9,8 @@
 // except according to those terms.
 
 use std::fs;
-use std::path::PathBuf;
+use std::path::{PathBuf, Path};
+use std::process::Command;
 
 use build::{Build, Compiler};
 
@@ -102,3 +103,42 @@ pub fn compiletest(build: &Build,
 
     build.run(&mut cmd);
 }
+
+pub fn docs(build: &Build, compiler: &Compiler) {
+    let mut stack = vec![build.src.join("src/doc")];
+
+    while let Some(p) = stack.pop() {
+        if p.is_dir() {
+            stack.extend(t!(p.read_dir()).map(|p| t!(p).path()));
+            continue
+        }
+
+        if p.extension().and_then(|s| s.to_str()) != Some("md") {
+            continue
+        }
+
+        println!("doc tests for: {}", p.display());
+        markdown_test(build, compiler, &p);
+    }
+}
+
+pub fn error_index(build: &Build, compiler: &Compiler) {
+    println!("Testing error-index stage{}", compiler.stage);
+
+    let output = testdir(build, compiler.host).join("error-index.md");
+    build.run(build.tool_cmd(compiler, "error_index_generator")
+                   .arg("markdown")
+                   .arg(&output)
+                   .env("CFG_BUILD", &build.config.build));
+
+    markdown_test(build, compiler, &output);
+}
+
+fn markdown_test(build: &Build, compiler: &Compiler, markdown: &Path) {
+    let mut cmd = Command::new(build.rustdoc(compiler));
+    build.add_rustc_lib_path(compiler, &mut cmd);
+    cmd.arg("--test");
+    cmd.arg(markdown);
+    cmd.arg("--test-args").arg(build.flags.args.join(" "));
+    build.run(&mut cmd);
+}

src/bootstrap/build/mod.rs

@@ -308,6 +308,12 @@ impl Build {
                     check::compiletest(self, &compiler, target.target,
                                        "compile-fail", "compile-fail-fulldeps")
                 }
+                CheckDocs { compiler } => {
+                    check::docs(self, &compiler);
+                }
+                CheckErrorIndex { compiler } => {
+                    check::error_index(self, &compiler);
+                }
 
                 DistDocs { stage } => dist::docs(self, stage, target.target),
                 DistMingw { _dummy } => dist::mingw(self, target.target),

src/bootstrap/build/step.rs

@@ -96,6 +96,8 @@ macro_rules! targets {
             (check_rpass_valgrind, CheckRPassValgrind { compiler: Compiler<'a> }),
             (check_rpass_full, CheckRPassFull { compiler: Compiler<'a> }),
             (check_cfail_full, CheckCFailFull { compiler: Compiler<'a> }),
+            (check_docs, CheckDocs { compiler: Compiler<'a> }),
+            (check_error_index, CheckErrorIndex { compiler: Compiler<'a> }),
 
             // Distribution targets, creating tarballs
             (dist, Dist { stage: u32 }),
@@ -341,7 +343,10 @@ impl<'a> Step<'a> {
                     self.check_rpass_valgrind(compiler),
                     self.check_rpass_full(compiler),
                     self.check_cfail_full(compiler),
+                    self.check_error_index(compiler),
+                    self.check_docs(compiler),
                     self.check_linkcheck(stage),
+                    self.check_tidy(stage),
                     self.dist(stage),
                 ]
             }
@@ -383,6 +388,12 @@ impl<'a> Step<'a> {
                 vec![self.librustc(compiler),
                      self.tool_compiletest(compiler.stage)]
             }
+            Source::CheckDocs { compiler } => {
+                vec![self.libstd(compiler)]
+            }
+            Source::CheckErrorIndex { compiler } => {
+                vec![self.libstd(compiler), self.tool_error_index(compiler.stage)]
+            }
 
             Source::ToolLinkchecker { stage } |
             Source::ToolTidy { stage } => {

src/doc/README.md

@@ -9,7 +9,7 @@ libraries.
 
 To generate HTML documentation from one source file/crate, do something like:
 
-~~~~
+~~~~text
 rustdoc --output html-doc/ --output-format html ../src/libstd/path.rs
 ~~~~
 
@@ -20,7 +20,7 @@ rustdoc --output html-doc/ --output-format html ../src/libstd/path.rs
 To generate an HTML version of a doc from Markdown manually, you can do
 something like:
 
-~~~~
+~~~~text
 rustdoc reference.md
 ~~~~
 

src/doc/style/errors/ergonomics.md

@@ -9,7 +9,7 @@ pattern.
 
 Prefer
 
-```rust
+```rust,ignore
 use std::io::{File, Open, Write, IoError};
 
 struct Info {
@@ -31,7 +31,7 @@ fn write_info(info: &Info) -> Result<(), IoError> {
 
 over
 
-```rust
+```rust,ignore
 use std::io::{File, Open, Write, IoError};
 
 struct Info {

src/doc/style/features/functions-and-methods/README.md

@@ -4,15 +4,15 @@
 
 Prefer
 
-```rust
+```rust,ignore
 impl Foo {
     pub fn frob(&self, w: widget) { ... }
 }
 ```
 
 over
 
-```rust
+```rust,ignore
 pub fn frob(foo: &Foo, w: widget) { ... }
 ```
 

src/doc/style/features/functions-and-methods/input.md

@@ -6,15 +6,15 @@
 
 Prefer
 
-```rust
+```rust,ignore
 fn foo(b: Bar) {
    // use b as owned, directly
 }
 ```
 
 over
 
-```rust
+```rust,ignore
 fn foo(b: &Bar) {
     let b = b.clone();
     // use b as owned after cloning
@@ -33,13 +33,13 @@ needed, not as a way of signaling that copies should be cheap to make.
 
 Prefer
 
-```rust
+```rust,ignore
 fn foo(b: Bar) -> Bar { ... }
 ```
 
 over
 
-```rust
+```rust,ignore
 fn foo(b: Box<Bar>) -> Box<Bar> { ... }
 ```
 
@@ -56,13 +56,13 @@ it becomes.
 
 Prefer
 
-```rust
+```rust,ignore
 fn foo<T: Iterator<i32>>(c: T) { ... }
 ```
 
 over any of
 
-```rust
+```rust,ignore
 fn foo(c: &[i32]) { ... }
 fn foo(c: &Vec<i32>) { ... }
 fn foo(c: &SomeOtherCollection<i32>) { ... }
@@ -83,14 +83,14 @@ concrete nor overly abstract. See the discussion on
 
 Prefer either of
 
-```rust
+```rust,ignore
 fn foo(b: &Bar) { ... }
 fn foo(b: &mut Bar) { ... }
 ```
 
 over
 
-```rust
+```rust,ignore
 fn foo(b: Bar) { ... }
 ```
 
@@ -101,13 +101,13 @@ ownership is actually needed.
 
 Prefer
 
-```rust
+```rust,ignore
 fn foo() -> (Bar, Bar)
 ```
 
 over
 
-```rust
+```rust,ignore
 fn foo(output: &mut Bar) -> Bar
 ```
 
@@ -120,7 +120,7 @@ multiple values, it should do so via one of these types.
 The primary exception: sometimes a function is meant to modify data
 that the caller already owns, for example to re-use a buffer:
 
-```rust
+```rust,ignore
 fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize>
 ```
 
@@ -146,7 +146,7 @@ Choose an argument type that rules out bad inputs.
 
 For example, prefer
 
-```rust
+```rust,ignore
 enum FooMode {
     Mode1,
     Mode2,
@@ -157,7 +157,7 @@ fn foo(mode: FooMode) { ... }
 
 over
 
-```rust
+```rust,ignore
 fn foo(mode2: bool, mode3: bool) {
     assert!(!mode2 || !mode3);
     ...

src/doc/style/features/functions-and-methods/output.md

@@ -16,7 +16,7 @@ API.
 
 Prefer
 
-```rust
+```rust,ignore
 struct SearchResult {
     found: bool,          // item in container?
     expected_index: usize // what would the item's index be?
@@ -26,27 +26,27 @@ fn binary_search(&self, k: Key) -> SearchResult
 ```
 or
 
-```rust
+```rust,ignore
 fn binary_search(&self, k: Key) -> (bool, usize)
 ```
 
 over
 
-```rust
+```rust,ignore
 fn binary_search(&self, k: Key) -> bool
 ```
 
 #### Yield back ownership:
 
 Prefer
 
-```rust
+```rust,ignore
 fn from_utf8_owned(vv: Vec<u8>) -> Result<String, Vec<u8>>
 ```
 
 over
 
-```rust
+```rust,ignore
 fn from_utf8_owned(vv: Vec<u8>) -> Option<String>
 ```
 

src/doc/style/features/let.md

@@ -4,7 +4,7 @@
 
 Prefer
 
-```rust
+```rust,ignore
 fn use_mutex(m: sync::mutex::Mutex<i32>) {
     let guard = m.lock();
     do_work(guard);
@@ -15,7 +15,7 @@ fn use_mutex(m: sync::mutex::Mutex<i32>) {
 
 over
 
-```rust
+```rust,ignore
 fn use_mutex(m: sync::mutex::Mutex<i32>) {
     do_work(m.lock());
     // do other work
@@ -32,7 +32,7 @@ explicitly `let`-bound to make the lifetime clear. Consider using an explicit
 
 Prefer
 
-```rust
+```rust,ignore
 let foo = match bar {
     Baz => 0,
     Quux => 1
@@ -41,7 +41,7 @@ let foo = match bar {
 
 over
 
-```rust
+```rust,ignore
 let foo;
 match bar {
     Baz => {
@@ -60,14 +60,14 @@ conditional expression.
 
 Prefer
 
-```rust
+```rust,ignore
 let v = s.iter().map(|x| x * 2)
                 .collect::<Vec<_>>();
 ```
 
 over
 
-```rust
+```rust,ignore
 let v: Vec<_> = s.iter().map(|x| x * 2)
                         .collect();
 ```
@@ -87,7 +87,7 @@ the type by explicit generics instantiation, which is usually more clear.
 
 Use `mut` bindings to signal the span during which a value is mutated:
 
-```rust
+```rust,ignore
 let mut v = Vec::new();
 // push things onto v
 let v = v;

src/doc/style/features/match.md

@@ -4,7 +4,7 @@
 
 Prefer
 
-~~~~
+~~~~ignore
 match *foo {
     X(...) => ...
     Y(...) => ...
@@ -13,7 +13,7 @@ match *foo {
 
 over
 
-~~~~
+~~~~ignore
 match foo {
     box X(...) => ...
     box Y(...) => ...