From 52b83d7e26e2ef3691f2e2d80588558c8f59af19 Mon Sep 17 00:00:00 2001 From: David Wood Date: Sat, 19 May 2018 16:21:17 +0100 Subject: [PATCH] Added rustdoc documentation step outputting into compiler documentation. --- src/bootstrap/builder.rs | 4 +- src/bootstrap/doc.rs | 88 +++++++++++++++++++++++++++++++++++++--- 2 files changed, 84 insertions(+), 8 deletions(-) diff --git a/src/bootstrap/builder.rs b/src/bootstrap/builder.rs index cd646b76e83..7b55a94a91c 100644 --- a/src/bootstrap/builder.rs +++ b/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::RustcBook, doc::CargoBook), + doc::Rustdoc, doc::ErrorIndex, doc::Nomicon, doc::Reference, doc::RustdocBook, + 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, diff --git a/src/bootstrap/doc.rs b/src/bootstrap/doc.rs index 16f4b29dcce..65493b9cfae 100644 --- a/src/bootstrap/doc.rs +++ b/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"; ); @@ -665,8 +665,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) { @@ -676,21 +680,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); @@ -729,6 +735,76 @@ fn find_compiler_crates( } } +#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)] +pub struct Rustdoc { + stage: u32, + target: Interned, +} + +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,