diff options
Diffstat (limited to 'src/bootstrap/doc.rs')
| -rw-r--r-- | src/bootstrap/doc.rs | 194 |
1 files changed, 67 insertions, 127 deletions
diff --git a/src/bootstrap/doc.rs b/src/bootstrap/doc.rs index ea06caf9c..2c6fd1e1d 100644 --- a/src/bootstrap/doc.rs +++ b/src/bootstrap/doc.rs @@ -85,18 +85,6 @@ book!( StyleGuide, "src/doc/style-guide", "style-guide"; ); -fn open(builder: &Builder<'_>, path: impl AsRef<Path>) { - if builder.config.dry_run || !builder.config.cmd.open() { - return; - } - - let path = path.as_ref(); - builder.info(&format!("Opening doc {}", path.display())); - if let Err(err) = opener::open(path) { - builder.info(&format!("{}\n", err)); - } -} - // "library/std" -> ["library", "std"] // // Used for deciding whether a particular step is one requested by the user on @@ -163,7 +151,7 @@ impl Step for RustbookSrc { let index = out.join("index.html"); let rustbook = builder.tool_exe(Tool::Rustbook); let mut rustbook_cmd = builder.tool_cmd(Tool::Rustbook); - if builder.config.dry_run || up_to_date(&src, &index) && up_to_date(&rustbook, &index) { + if builder.config.dry_run() || up_to_date(&src, &index) && up_to_date(&rustbook, &index) { return; } builder.info(&format!("Rustbook ({}) - {}", target, name)); @@ -240,11 +228,9 @@ impl Step for TheBook { invoke_rustdoc(builder, compiler, &shared_assets, target, path); } - if builder.was_invoked_explicitly::<Self>(Kind::Doc) { - let out = builder.doc_out(target); - let index = out.join("book").join("index.html"); - open(builder, &index); - } + let out = builder.doc_out(target); + let index = out.join("book").join("index.html"); + builder.maybe_open_in_browser::<Self>(index); } } @@ -345,8 +331,8 @@ impl Step for Standalone { && up_to_date(&footer, &html) && up_to_date(&favicon, &html) && up_to_date(&full_toc, &html) - && (builder.config.dry_run || up_to_date(&version_info, &html)) - && (builder.config.dry_run || up_to_date(&rustdoc, &html)) + && (builder.config.dry_run() || up_to_date(&version_info, &html)) + && (builder.config.dry_run() || up_to_date(&rustdoc, &html)) { continue; } @@ -386,7 +372,7 @@ impl Step for Standalone { // with no particular explicit doc requested (e.g. library/core). if builder.paths.is_empty() || builder.was_invoked_explicitly::<Self>(Kind::Doc) { let index = out.join("index.html"); - open(builder, &index); + builder.open_in_browser(&index); } } } @@ -416,11 +402,11 @@ impl Step for SharedAssets { let version_input = builder.src.join("src").join("doc").join("version_info.html.template"); let version_info = out.join("version_info.html"); - if !builder.config.dry_run && !up_to_date(&version_input, &version_info) { + if !builder.config.dry_run() && !up_to_date(&version_input, &version_info) { let info = t!(fs::read_to_string(&version_input)) .replace("VERSION", &builder.rust_release()) - .replace("SHORT_HASH", builder.rust_info.sha_short().unwrap_or("")) - .replace("STAMP", builder.rust_info.sha().unwrap_or("")); + .replace("SHORT_HASH", builder.rust_info().sha_short().unwrap_or("")) + .replace("STAMP", builder.rust_info().sha().unwrap_or("")); t!(fs::write(&version_info, &info)); } @@ -434,6 +420,7 @@ impl Step for SharedAssets { pub struct Std { pub stage: u32, pub target: TargetSelection, + pub format: DocumentationFormat, } impl Step for Std { @@ -446,7 +433,15 @@ impl Step for Std { } fn make_run(run: RunConfig<'_>) { - run.builder.ensure(Std { stage: run.builder.top_stage, target: run.target }); + run.builder.ensure(Std { + stage: run.builder.top_stage, + target: run.target, + format: if run.builder.config.cmd.json() { + DocumentationFormat::JSON + } else { + DocumentationFormat::HTML + }, + }); } /// Compile all standard library documentation. @@ -456,19 +451,28 @@ impl Step for Std { fn run(self, builder: &Builder<'_>) { let stage = self.stage; let target = self.target; - let out = builder.doc_out(target); + let out = match self.format { + DocumentationFormat::HTML => builder.doc_out(target), + DocumentationFormat::JSON => builder.json_doc_out(target), + }; + t!(fs::create_dir_all(&out)); - builder.ensure(SharedAssets { target: self.target }); + if self.format == DocumentationFormat::HTML { + builder.ensure(SharedAssets { target: self.target }); + } let index_page = builder.src.join("src/doc/index.md").into_os_string(); - let mut extra_args = vec![ - OsStr::new("--markdown-css"), - OsStr::new("rust.css"), - OsStr::new("--markdown-no-toc"), - OsStr::new("--index-page"), - &index_page, - ]; + let mut extra_args = match self.format { + DocumentationFormat::HTML => vec![ + OsStr::new("--markdown-css"), + OsStr::new("rust.css"), + OsStr::new("--markdown-no-toc"), + OsStr::new("--index-page"), + &index_page, + ], + DocumentationFormat::JSON => vec![OsStr::new("--output-format"), OsStr::new("json")], + }; if !builder.config.docs_minification { extra_args.push(OsStr::new("--disable-minification")); @@ -492,59 +496,24 @@ impl Step for Std { }) .collect::<Vec<_>>(); - doc_std( - builder, - DocumentationFormat::HTML, - stage, - target, - &out, - &extra_args, - &requested_crates, - ); + doc_std(builder, self.format, stage, target, &out, &extra_args, &requested_crates); + + // Don't open if the format is json + if let DocumentationFormat::JSON = self.format { + return; + } // Look for library/std, library/core etc in the `x.py doc` arguments and // open the corresponding rendered docs. for requested_crate in requested_crates { if STD_PUBLIC_CRATES.iter().any(|k| *k == requested_crate.as_str()) { let index = out.join(requested_crate).join("index.html"); - open(builder, &index); + builder.open_in_browser(index); } } } } -#[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)] -pub struct JsonStd { - pub stage: u32, - pub target: TargetSelection, -} - -impl Step for JsonStd { - type Output = (); - const DEFAULT: bool = false; - - fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> { - let default = run.builder.config.docs && run.builder.config.cmd.json(); - run.all_krates("test").path("library").default_condition(default) - } - - fn make_run(run: RunConfig<'_>) { - run.builder.ensure(Std { stage: run.builder.top_stage, target: run.target }); - } - - /// Build JSON documentation for the standard library crates. - /// - /// This is largely just a wrapper around `cargo doc`. - fn run(self, builder: &Builder<'_>) { - let stage = self.stage; - let target = self.target; - let out = builder.json_doc_out(target); - t!(fs::create_dir_all(&out)); - let extra_args = [OsStr::new("--output-format"), OsStr::new("json")]; - doc_std(builder, DocumentationFormat::JSON, stage, target, &out, &extra_args, &[]) - } -} - /// Name of the crates that are visible to consumers of the standard library. /// Documentation for internal crates is handled by the rustc step, so internal crates will show /// up there. @@ -557,7 +526,7 @@ impl Step for JsonStd { const STD_PUBLIC_CRATES: [&str; 5] = ["core", "alloc", "std", "proc_macro", "test"]; #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)] -enum DocumentationFormat { +pub enum DocumentationFormat { HTML, JSON, } @@ -597,27 +566,22 @@ fn doc_std( ); } let compiler = builder.compiler(stage, builder.config.build); + + let target_doc_dir_name = if format == DocumentationFormat::JSON { "json-doc" } else { "doc" }; + let target_dir = + builder.stage_out(compiler, Mode::Std).join(target.triple).join(target_doc_dir_name); + // This is directory where the compiler will place the output of the command. // We will then copy the files from this directory into the final `out` directory, the specified // as a function parameter. - let out_dir = builder.stage_out(compiler, Mode::Std).join(target.triple).join("doc"); - // `cargo` uses the same directory for both JSON docs and HTML docs. - // This could lead to cross-contamination when copying files into the specified `out` directory. - // For example: - // ```bash - // x doc std - // x doc std --json - // ``` - // could lead to HTML docs being copied into the JSON docs output directory. - // To avoid this issue, we clean the doc folder before invoking `cargo`. - if out_dir.exists() { - builder.remove_dir(&out_dir); - } + let out_dir = target_dir.join(target.triple).join("doc"); let run_cargo_rustdoc_for = |package: &str| { let mut cargo = builder.cargo(compiler, Mode::Std, SourceType::InTree, target, "rustdoc"); compile::std_cargo(builder, target, compiler.stage, &mut cargo); cargo + .arg("--target-dir") + .arg(&*target_dir.to_string_lossy()) .arg("-p") .arg(package) .arg("-Zskip-rustdoc-fingerprint") @@ -759,13 +723,13 @@ impl Step for Rustc { // Let's open the first crate documentation page: if let Some(krate) = to_open { let index = out.join(krate).join("index.html"); - open(builder, &index); + builder.open_in_browser(index); } } } macro_rules! tool_doc { - ($tool: ident, $should_run: literal, $path: literal, [$($krate: literal),+ $(,)?], in_tree = $in_tree:expr $(,)?) => { + ($tool: ident, $should_run: literal, $path: literal, [$($krate: literal),+ $(,)?] $(,)?) => { #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)] pub struct $tool { target: TargetSelection, @@ -821,12 +785,6 @@ macro_rules! tool_doc { t!(fs::create_dir_all(&out_dir)); t!(symlink_dir_force(&builder.config, &out, &out_dir)); - let source_type = if $in_tree == true { - SourceType::InTree - } else { - SourceType::Submodule - }; - // Build cargo command. let mut cargo = prepare_tool_cargo( builder, @@ -835,7 +793,7 @@ macro_rules! tool_doc { target, "doc", $path, - source_type, + SourceType::InTree, &[], ); @@ -851,38 +809,21 @@ macro_rules! tool_doc { cargo.rustdocflag("--show-type-layout"); cargo.rustdocflag("--generate-link-to-definition"); cargo.rustdocflag("-Zunstable-options"); - if $in_tree == true { - builder.run(&mut cargo.into()); - } else { - // Allow out-of-tree docs to fail (since the tool might be in a broken state). - if !builder.try_run(&mut cargo.into()) { - builder.info(&format!( - "WARNING: tool {} failed to document; ignoring failure because it is an out-of-tree tool", - stringify!($tool).to_lowercase(), - )); - } - } + builder.run(&mut cargo.into()); } } } } -tool_doc!( - Rustdoc, - "rustdoc-tool", - "src/tools/rustdoc", - ["rustdoc", "rustdoc-json-types"], - in_tree = true -); +tool_doc!(Rustdoc, "rustdoc-tool", "src/tools/rustdoc", ["rustdoc", "rustdoc-json-types"],); tool_doc!( Rustfmt, "rustfmt-nightly", "src/tools/rustfmt", ["rustfmt-nightly", "rustfmt-config_proc_macro"], - in_tree = true ); -tool_doc!(Clippy, "clippy", "src/tools/clippy", ["clippy_utils"], in_tree = true); -tool_doc!(Miri, "miri", "src/tools/miri", ["miri"], in_tree = false); +tool_doc!(Clippy, "clippy", "src/tools/clippy", ["clippy_utils"]); +tool_doc!(Miri, "miri", "src/tools/miri", ["miri"]); #[derive(Ord, PartialOrd, Debug, Copy, Clone, Hash, PartialEq, Eq)] pub struct ErrorIndex { @@ -956,7 +897,7 @@ impl Step for UnstableBookGen { } fn symlink_dir_force(config: &Config, src: &Path, dst: &Path) -> io::Result<()> { - if config.dry_run { + if config.dry_run() { return Ok(()); } if let Ok(m) = fs::symlink_metadata(dst) { @@ -1021,7 +962,7 @@ impl Step for RustcBook { cmd.arg("--rustc"); cmd.arg(&rustc); cmd.arg("--rustc-target").arg(&self.target.rustc_target_arg()); - if builder.config.verbose() { + if builder.is_verbose() { cmd.arg("--verbose"); } if self.validate { @@ -1042,10 +983,9 @@ impl Step for RustcBook { name: INTERNER.intern_str("rustc"), src: INTERNER.intern_path(out_base), }); - if builder.was_invoked_explicitly::<Self>(Kind::Doc) { - let out = builder.doc_out(self.target); - let index = out.join("rustc").join("index.html"); - open(builder, &index); - } + + let out = builder.doc_out(self.target); + let index = out.join("rustc").join("index.html"); + builder.maybe_open_in_browser::<Self>(index); } } |