From 6a541937dc314cc9e71062a82119b170dd27e995 Mon Sep 17 00:00:00 2001
From: Alex Crichton <alex@alexcrichton.com>
Date: Mon, 7 Mar 2016 22:36:21 -0800
Subject: [PATCH] rustbuild: Add crate documentation generation

Run `cargo doc` to generate all documentation for the standard library, and also
add a target which generates documentation for the compiler as well (but don't
enable it by default).
---
 src/bootstrap/build/doc.rs  | 39 ++++++++++++++++++++++++++++++++++++-
 src/bootstrap/build/mod.rs  | 10 +++++++++-
 src/bootstrap/build/step.rs | 13 ++++++++++++-
 src/bootstrap/build/util.rs |  1 -
 4 files changed, 59 insertions(+), 4 deletions(-)

diff --git a/src/bootstrap/build/doc.rs b/src/bootstrap/build/doc.rs
index 937a234bec8..02eda0e7b58 100644
--- a/src/bootstrap/build/doc.rs
+++ b/src/bootstrap/build/doc.rs
@@ -13,7 +13,7 @@ use std::fs::{self, File};
 use std::io::prelude::*;
 
 use build::{Build, Compiler};
-use build::util::up_to_date;
+use build::util::{up_to_date, cp_r};
 
 pub fn rustbook(build: &Build, stage: u32, host: &str, name: &str, out: &Path) {
     t!(fs::create_dir_all(out));
@@ -102,3 +102,40 @@ pub fn standalone(build: &Build, stage: u32, host: &str, out: &Path) {
         build.run(&mut cmd);
     }
 }
+
+pub fn std(build: &Build, stage: u32, host: &str, out: &Path) {
+    println!("Documenting stage{} std ({})", stage, host);
+    let compiler = Compiler::new(stage, host);
+    let out_dir = build.stage_out(stage, host, true)
+                       .join(host).join("doc");
+    let rustdoc = build.tool(&compiler, "rustdoc");
+    if !up_to_date(&rustdoc, &out_dir.join("std/index.html")) {
+        t!(fs::remove_dir_all(&out_dir));
+    }
+
+    let mut cargo = build.cargo(stage, &compiler, true, host,
+                                "doc");
+    cargo.arg("--manifest-path")
+         .arg(build.src.join("src/rustc/std_shim/Cargo.toml"))
+         .arg("--features").arg(build.std_features());
+    build.run(&mut cargo);
+    cp_r(&out_dir, out)
+}
+
+pub fn rustc(build: &Build, stage: u32, host: &str, out: &Path) {
+    println!("Documenting stage{} compiler ({})", stage, host);
+    let compiler = Compiler::new(stage, host);
+    let out_dir = build.stage_out(stage, host, false)
+                       .join(host).join("doc");
+    let rustdoc = build.tool(&compiler, "rustdoc");
+    if !up_to_date(&rustdoc, &out_dir.join("rustc/index.html")) {
+        t!(fs::remove_dir_all(&out_dir));
+    }
+    let mut cargo = build.cargo(stage, &compiler, false, host,
+                                "doc");
+    cargo.arg("--manifest-path")
+         .arg(build.src.join("src/rustc/Cargo.toml"))
+         .arg("--features").arg(build.rustc_features(stage));
+    build.run(&mut cargo);
+    cp_r(&out_dir, out)
+}
diff --git a/src/bootstrap/build/mod.rs b/src/bootstrap/build/mod.rs
index 98d821b8b90..05920a480a9 100644
--- a/src/bootstrap/build/mod.rs
+++ b/src/bootstrap/build/mod.rs
@@ -179,7 +179,15 @@ impl Build {
                 DocStandalone { stage } => {
                     doc::standalone(self, stage, target.target, &doc_out);
                 }
-                Doc { .. } => {} // pseudo-step
+                DocStd { stage } => {
+                    doc::std(self, stage, target.target, &doc_out);
+                }
+                DocRustc { stage } => {
+                    doc::rustc(self, stage, target.target, &doc_out);
+                }
+
+                Doc { .. } | // pseudo-steps
+                Check { .. } => {}
             }
         }
     }
diff --git a/src/bootstrap/build/step.rs b/src/bootstrap/build/step.rs
index fbdcddf3aa0..fc8d366faac 100644
--- a/src/bootstrap/build/step.rs
+++ b/src/bootstrap/build/step.rs
@@ -62,6 +62,8 @@ macro_rules! targets {
             (doc_nomicon, DocNomicon { stage: u32 }),
             (doc_style, DocStyle { stage: u32 }),
             (doc_standalone, DocStandalone { stage: u32 }),
+            (doc_std, DocStd { stage: u32 }),
+            (doc_rustc, DocRustc { stage: u32 }),
 
             // Steps for running tests. The 'check' target is just a pseudo
             // target to depend on a bunch of others.
@@ -182,6 +184,8 @@ fn add_steps<'a>(build: &'a Build,
             "doc-standalone" => targets.push(host.doc_standalone(stage)),
             "doc-nomicon" => targets.push(host.doc_nomicon(stage)),
             "doc-book" => targets.push(host.doc_book(stage)),
+            "doc-std" => targets.push(host.doc_std(stage)),
+            "doc-rustc" => targets.push(host.doc_rustc(stage)),
             "doc" => targets.push(host.doc(stage)),
             "check" => targets.push(host.check(stage, compiler)),
             _ => panic!("unknown build target: `{}`", step),
@@ -239,15 +243,22 @@ impl<'a> Step<'a> {
                 vec![self.llvm(()).target(&build.config.build)]
             }
             Source::Llvm { _dummy } => Vec::new(),
+            Source::DocStd { stage } => {
+                vec![self.libstd(stage, self.compiler(stage))]
+            }
             Source::DocBook { stage } |
             Source::DocNomicon { stage } |
             Source::DocStyle { stage } |
             Source::DocStandalone { stage } => {
                 vec![self.rustc(stage)]
             }
+            Source::DocRustc { stage } => {
+                vec![self.doc_std(stage)]
+            }
             Source::Doc { stage } => {
                 vec![self.doc_book(stage), self.doc_nomicon(stage),
-                     self.doc_style(stage), self.doc_standalone(stage)]
+                     self.doc_style(stage), self.doc_standalone(stage),
+                     self.doc_std(stage)]
             }
             Source::Check { stage, compiler: _ } => {
                 vec![]
diff --git a/src/bootstrap/build/util.rs b/src/bootstrap/build/util.rs
index 6c700671f11..35d22ee5d26 100644
--- a/src/bootstrap/build/util.rs
+++ b/src/bootstrap/build/util.rs
@@ -30,7 +30,6 @@ pub fn mtime(path: &Path) -> FileTime {
     }).unwrap_or(FileTime::zero())
 }
 
-#[allow(dead_code)] // this will be used soon
 pub fn cp_r(src: &Path, dst: &Path) {
     for f in t!(fs::read_dir(src)) {
         let f = t!(f);