Auto merge of #50892 - davidtwco:issue-50004, r=alexcrichton

Added rustdoc documentation to compiler docs.

Fixes #50004.

r? @alexcrichton
(since you reviewed the last PR about compiler docs)

src/bootstrap/builder.rs

@@ -352,8 +352,8 @@ impl<'a> Builder<'a> {
             Kind::Bench => describe!(test::Crate, test::CrateLibrustc),
             Kind::Doc => describe!(doc::UnstableBook, doc::UnstableBookGen, doc::TheBook,
                 doc::Standalone, doc::Std, doc::Test, doc::WhitelistedRustc, doc::Rustc,
-                doc::ErrorIndex, doc::Nomicon, doc::Reference, doc::Rustdoc, doc::RustByExample,
+                doc::Rustdoc, doc::ErrorIndex, doc::Nomicon, doc::Reference, doc::RustdocBook,
-                doc::RustcBook, doc::CargoBook),
+                doc::RustByExample, doc::RustcBook, doc::CargoBook),
             Kind::Dist => describe!(dist::Docs, dist::RustcDocs, dist::Mingw, dist::Rustc,
                 dist::DebuggerScripts, dist::Std, dist::Analysis, dist::Src,
                 dist::PlainSourceTarball, dist::Cargo, dist::Rls, dist::Rustfmt, dist::Extended,

src/bootstrap/doc.rs

@@ -28,7 +28,7 @@ use build_helper::up_to_date;
 
 use util::symlink_dir;
 use builder::{Builder, Compiler, RunConfig, ShouldRun, Step};
-use tool::Tool;
+use tool::{self, prepare_tool_cargo, Tool};
 use compile;
 use cache::{INTERNER, Interned};
 use config::Config;
@@ -70,7 +70,7 @@ macro_rules! book {
 book!(
     Nomicon, "src/doc/nomicon", "nomicon";
     Reference, "src/doc/reference", "reference";
-    Rustdoc, "src/doc/rustdoc", "rustdoc";
+    RustdocBook, "src/doc/rustdoc", "rustdoc";
     RustcBook, "src/doc/rustc", "rustc";
     RustByExample, "src/doc/rust-by-example", "rust-by-example";
 );
@@ -671,8 +671,12 @@ impl Step for Rustc {
         let stage = self.stage;
         let target = self.target;
         builder.info(&format!("Documenting stage{} compiler ({})", stage, target));
+
+        // This is the intended out directory for compiler documentation.
         let out = builder.compiler_doc_out(target);
         t!(fs::create_dir_all(&out));
+
+        // Get the correct compiler for this stage.
         let compiler = builder.compiler(stage, builder.config.build);
         let rustdoc = builder.rustdoc(compiler.host);
         let compiler = if builder.force_use_stage1(compiler, target) {
@@ -682,21 +686,23 @@ impl Step for Rustc {
         };
 
         if !builder.config.compiler_docs {
-            builder.info(&format!("\tskipping - compiler docs disabled"));
+            builder.info(&format!("\tskipping - compiler/librustdoc docs disabled"));
             return;
         }
 
-        // Build libstd docs so that we generate relative links
+        // Build libstd docs so that we generate relative links.
         builder.ensure(Std { stage, target });
 
+        // Build rustc.
         builder.ensure(compile::Rustc { compiler, target });
-        let out_dir = builder.stage_out(compiler, Mode::Librustc)
+
-                           .join(target).join("doc");
         // We do not symlink to the same shared folder that already contains std library
         // documentation from previous steps as we do not want to include that.
+        let out_dir = builder.stage_out(compiler, Mode::Librustc).join(target).join("doc");
         builder.clear_if_dirty(&out, &rustdoc);
         t!(symlink_dir_force(&builder.config, &out, &out_dir));
 
+        // Build cargo command.
         let mut cargo = builder.cargo(compiler, Mode::Librustc, target, "doc");
         cargo.env("RUSTDOCFLAGS", "--document-private-items");
         compile::rustc_cargo(builder, &mut cargo);
@@ -735,6 +741,76 @@ fn find_compiler_crates(
     }
 }
 
+#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
+pub struct Rustdoc {
+    stage: u32,
+    target: Interned<String>,
+}
+
+impl Step for Rustdoc {
+    type Output = ();
+    const DEFAULT: bool = true;
+    const ONLY_HOSTS: bool = true;
+
+    fn should_run(run: ShouldRun) -> ShouldRun {
+        run.krate("rustdoc-tool")
+    }
+
+    fn make_run(run: RunConfig) {
+        run.builder.ensure(Rustdoc {
+            stage: run.builder.top_stage,
+            target: run.target,
+        });
+    }
+
+    /// Generate compiler documentation.
+    ///
+    /// This will generate all documentation for compiler and dependencies.
+    /// Compiler documentation is distributed separately, so we make sure
+    /// we do not merge it with the other documentation from std, test and
+    /// proc_macros. This is largely just a wrapper around `cargo doc`.
+    fn run(self, builder: &Builder) {
+        let stage = self.stage;
+        let target = self.target;
+        builder.info(&format!("Documenting stage{} rustdoc ({})", stage, target));
+
+        // This is the intended out directory for compiler documentation.
+        let out = builder.compiler_doc_out(target);
+        t!(fs::create_dir_all(&out));
+
+        // Get the correct compiler for this stage.
+        let compiler = builder.compiler(stage, builder.config.build);
+        let rustdoc = builder.rustdoc(compiler.host);
+        let compiler = if builder.force_use_stage1(compiler, target) {
+            builder.compiler(1, compiler.host)
+        } else {
+            compiler
+        };
+
+        if !builder.config.compiler_docs {
+            builder.info(&format!("\tskipping - compiler/librustdoc docs disabled"));
+            return;
+        }
+
+        // Build libstd docs so that we generate relative links.
+        builder.ensure(Std { stage, target });
+
+        // Build rustdoc.
+        builder.ensure(tool::Rustdoc { host: compiler.host });
+
+        // Symlink compiler docs to the output directory of rustdoc documentation.
+        let out_dir = builder.stage_out(compiler, Mode::Tool).join(target).join("doc");
+        t!(fs::create_dir_all(&out_dir));
+        builder.clear_if_dirty(&out, &rustdoc);
+        t!(symlink_dir_force(&builder.config, &out, &out_dir));
+
+        // Build cargo command.
+        let mut cargo = prepare_tool_cargo(builder, compiler, target, "doc", "src/tools/rustdoc");
+        cargo.env("RUSTDOCFLAGS", "--document-private-items");
+        builder.run(&mut cargo);
+    }
+}
+
 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
 pub struct ErrorIndex {
     target: Interned<String>,