1 //! Documentation generation for rustbuilder.
3 //! This module implements generation for all bits and pieces of documentation
4 //! for the Rust project. This notably includes suites like the rust book, the
5 //! nomicon, rust by example, standalone documentation, etc.
7 //! Everything here is basically just a shim around calling either `rustbook` or
10 use std::collections::HashSet;
13 use std::path::{Path, PathBuf};
16 use build_helper::{t, up_to_date};
18 use crate::builder::{Builder, Compiler, RunConfig, ShouldRun, Step};
19 use crate::cache::{Interned, INTERNER};
21 use crate::config::Config;
22 use crate::tool::{self, prepare_tool_cargo, SourceType, Tool};
23 use crate::util::symlink_dir;
26 ($($name:ident, $path:expr, $book_name:expr;)+) => {
28 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
30 target: Interned<String>,
35 const DEFAULT: bool = true;
37 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
38 let builder = run.builder;
39 run.path($path).default_condition(builder.config.docs)
42 fn make_run(run: RunConfig<'_>) {
43 run.builder.ensure($name {
48 fn run(self, builder: &Builder<'_>) {
49 builder.ensure(RustbookSrc {
51 name: INTERNER.intern_str($book_name),
52 src: INTERNER.intern_path(builder.src.join($path)),
60 // NOTE: When adding a book here, make sure to ALSO build the book by
61 // adding a build step in `src/bootstrap/builder.rs`!
63 CargoBook, "src/tools/cargo/src/doc", "cargo";
64 EditionGuide, "src/doc/edition-guide", "edition-guide";
65 EmbeddedBook, "src/doc/embedded-book", "embedded-book";
66 Nomicon, "src/doc/nomicon", "nomicon";
67 Reference, "src/doc/reference", "reference";
68 RustByExample, "src/doc/rust-by-example", "rust-by-example";
69 RustcBook, "src/doc/rustc", "rustc";
70 RustdocBook, "src/doc/rustdoc", "rustdoc";
73 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
74 pub struct UnstableBook {
75 target: Interned<String>,
78 impl Step for UnstableBook {
80 const DEFAULT: bool = true;
82 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
83 let builder = run.builder;
84 run.path("src/doc/unstable-book").default_condition(builder.config.docs)
87 fn make_run(run: RunConfig<'_>) {
88 run.builder.ensure(UnstableBook { target: run.target });
91 fn run(self, builder: &Builder<'_>) {
92 builder.ensure(UnstableBookGen { target: self.target });
93 builder.ensure(RustbookSrc {
95 name: INTERNER.intern_str("unstable-book"),
96 src: INTERNER.intern_path(builder.md_doc_out(self.target).join("unstable-book")),
101 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
103 target: Interned<String>,
104 name: Interned<String>,
105 src: Interned<PathBuf>,
108 impl Step for RustbookSrc {
111 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
115 /// Invoke `rustbook` for `target` for the doc book `name` from the `src` path.
117 /// This will not actually generate any documentation if the documentation has
118 /// already been generated.
119 fn run(self, builder: &Builder<'_>) {
120 let target = self.target;
121 let name = self.name;
123 let out = builder.doc_out(target);
124 t!(fs::create_dir_all(&out));
126 let out = out.join(name);
127 let index = out.join("index.html");
128 let rustbook = builder.tool_exe(Tool::Rustbook);
129 let mut rustbook_cmd = builder.tool_cmd(Tool::Rustbook);
130 if up_to_date(&src, &index) && up_to_date(&rustbook, &index) {
133 builder.info(&format!("Rustbook ({}) - {}", target, name));
134 let _ = fs::remove_dir_all(&out);
136 builder.run(rustbook_cmd.arg("build").arg(&src).arg("-d").arg(out));
140 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
143 target: Interned<String>,
146 impl Step for TheBook {
148 const DEFAULT: bool = true;
150 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
151 let builder = run.builder;
152 run.path("src/doc/book").default_condition(builder.config.docs)
155 fn make_run(run: RunConfig<'_>) {
156 run.builder.ensure(TheBook {
157 compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
162 /// Builds the book and associated stuff.
164 /// We need to build:
167 /// * Older edition redirects
168 /// * Version info and CSS
171 fn run(self, builder: &Builder<'_>) {
172 let compiler = self.compiler;
173 let target = self.target;
176 builder.ensure(RustbookSrc {
178 name: INTERNER.intern_str("book"),
179 src: INTERNER.intern_path(builder.src.join("src/doc/book")),
182 // building older edition redirects
183 for edition in &["first-edition", "second-edition", "2018-edition"] {
184 builder.ensure(RustbookSrc {
186 name: INTERNER.intern_string(format!("book/{}", edition)),
187 src: INTERNER.intern_path(builder.src.join("src/doc/book").join(edition)),
191 // build the version info page and CSS
192 builder.ensure(Standalone { compiler, target });
194 // build the redirect pages
195 builder.info(&format!("Documenting book redirect pages ({})", target));
196 for file in t!(fs::read_dir(builder.src.join("src/doc/book/redirects"))) {
198 let path = file.path();
199 let path = path.to_str().unwrap();
201 invoke_rustdoc(builder, compiler, target, path);
207 builder: &Builder<'_>,
209 target: Interned<String>,
212 let out = builder.doc_out(target);
214 let path = builder.src.join("src/doc").join(markdown);
216 let header = builder.src.join("src/doc/redirect.inc");
217 let footer = builder.src.join("src/doc/footer.inc");
218 let version_info = out.join("version_info.html");
220 let mut cmd = builder.rustdoc_cmd(compiler);
222 let out = out.join("book");
224 cmd.arg("--html-after-content")
226 .arg("--html-before-content")
228 .arg("--html-in-header")
230 .arg("--markdown-no-toc")
231 .arg("--markdown-playground-url")
232 .arg("https://play.rust-lang.org/")
236 .arg("--markdown-css")
239 builder.run(&mut cmd);
242 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
243 pub struct Standalone {
245 target: Interned<String>,
248 impl Step for Standalone {
250 const DEFAULT: bool = true;
252 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
253 let builder = run.builder;
254 run.path("src/doc").default_condition(builder.config.docs)
257 fn make_run(run: RunConfig<'_>) {
258 run.builder.ensure(Standalone {
259 compiler: run.builder.compiler(run.builder.top_stage, run.builder.config.build),
264 /// Generates all standalone documentation as compiled by the rustdoc in `stage`
265 /// for the `target` into `out`.
267 /// This will list all of `src/doc` looking for markdown files and appropriately
268 /// perform transformations like substituting `VERSION`, `SHORT_HASH`, and
269 /// `STAMP` along with providing the various header/footer HTML we've customized.
271 /// In the end, this is just a glorified wrapper around rustdoc!
272 fn run(self, builder: &Builder<'_>) {
273 let target = self.target;
274 let compiler = self.compiler;
275 builder.info(&format!("Documenting standalone ({})", target));
276 let out = builder.doc_out(target);
277 t!(fs::create_dir_all(&out));
279 let favicon = builder.src.join("src/doc/favicon.inc");
280 let footer = builder.src.join("src/doc/footer.inc");
281 let full_toc = builder.src.join("src/doc/full-toc.inc");
282 t!(fs::copy(builder.src.join("src/doc/rust.css"), out.join("rust.css")));
284 let version_input = builder.src.join("src/doc/version_info.html.template");
285 let version_info = out.join("version_info.html");
287 if !builder.config.dry_run && !up_to_date(&version_input, &version_info) {
288 let info = t!(fs::read_to_string(&version_input))
289 .replace("VERSION", &builder.rust_release())
290 .replace("SHORT_HASH", builder.rust_info.sha_short().unwrap_or(""))
291 .replace("STAMP", builder.rust_info.sha().unwrap_or(""));
292 t!(fs::write(&version_info, &info));
295 for file in t!(fs::read_dir(builder.src.join("src/doc"))) {
297 let path = file.path();
298 let filename = path.file_name().unwrap().to_str().unwrap();
299 if !filename.ends_with(".md") || filename == "README.md" {
303 let html = out.join(filename).with_extension("html");
304 let rustdoc = builder.rustdoc(compiler);
305 if up_to_date(&path, &html)
306 && up_to_date(&footer, &html)
307 && up_to_date(&favicon, &html)
308 && up_to_date(&full_toc, &html)
309 && (builder.config.dry_run || up_to_date(&version_info, &html))
310 && (builder.config.dry_run || up_to_date(&rustdoc, &html))
315 let mut cmd = builder.rustdoc_cmd(compiler);
316 cmd.arg("--html-after-content")
318 .arg("--html-before-content")
320 .arg("--html-in-header")
322 .arg("--markdown-no-toc")
324 .arg(&builder.src.join("src/doc/index.md"))
325 .arg("--markdown-playground-url")
326 .arg("https://play.rust-lang.org/")
331 if filename == "not_found.md" {
332 cmd.arg("--markdown-css").arg("https://doc.rust-lang.org/rust.css");
334 cmd.arg("--markdown-css").arg("rust.css");
336 builder.run(&mut cmd);
341 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
344 pub target: Interned<String>,
349 const DEFAULT: bool = true;
351 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
352 let builder = run.builder;
353 run.all_krates("test").default_condition(builder.config.docs)
356 fn make_run(run: RunConfig<'_>) {
357 run.builder.ensure(Std { stage: run.builder.top_stage, target: run.target });
360 /// Compile all standard library documentation.
362 /// This will generate all documentation for the standard library and its
363 /// dependencies. This is largely just a wrapper around `cargo doc`.
364 fn run(self, builder: &Builder<'_>) {
365 let stage = self.stage;
366 let target = self.target;
367 builder.info(&format!("Documenting stage{} std ({})", stage, target));
368 let out = builder.doc_out(target);
369 t!(fs::create_dir_all(&out));
370 let compiler = builder.compiler(stage, builder.config.build);
372 builder.ensure(compile::Std { compiler, target });
373 let out_dir = builder.stage_out(compiler, Mode::Std).join(target).join("doc");
375 // Here what we're doing is creating a *symlink* (directory junction on
376 // Windows) to the final output location. This is not done as an
377 // optimization but rather for correctness. We've got three trees of
378 // documentation, one for std, one for test, and one for rustc. It's then
379 // our job to merge them all together.
381 // Unfortunately rustbuild doesn't know nearly as well how to merge doc
382 // trees as rustdoc does itself, so instead of actually having three
383 // separate trees we just have rustdoc output to the same location across
386 // This way rustdoc generates output directly into the output, and rustdoc
387 // will also directly handle merging.
388 let my_out = builder.crate_doc_out(target);
389 t!(symlink_dir_force(&builder.config, &my_out, &out_dir));
390 t!(fs::copy(builder.src.join("src/doc/rust.css"), out.join("rust.css")));
392 let run_cargo_rustdoc_for = |package: &str| {
393 let mut cargo = builder.cargo(compiler, Mode::Std, target, "rustdoc");
394 compile::std_cargo(builder, target, &mut cargo);
396 // Keep a whitelist so we do not build internal stdlib crates, these will be
397 // build by the rustc step later if enabled.
398 cargo.arg("-Z").arg("unstable-options").arg("-p").arg(package);
399 // Create all crate output directories first to make sure rustdoc uses
401 // FIXME: Cargo should probably do this itself.
402 t!(fs::create_dir_all(out_dir.join(package)));
405 .arg("--markdown-css")
407 .arg("--markdown-no-toc")
408 .arg("--generate-redirect-pages")
409 .arg("--resource-suffix")
410 .arg(crate::channel::CFG_RELEASE_NUM)
412 .arg(&builder.src.join("src/doc/index.md"));
414 builder.run(&mut cargo.into());
416 for krate in &["alloc", "core", "std", "proc_macro", "test"] {
417 run_cargo_rustdoc_for(krate);
419 builder.cp_r(&my_out, &out);
423 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
426 target: Interned<String>,
429 impl Step for Rustc {
431 const DEFAULT: bool = true;
432 const ONLY_HOSTS: bool = true;
434 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
435 let builder = run.builder;
436 run.krate("rustc-main").default_condition(builder.config.docs)
439 fn make_run(run: RunConfig<'_>) {
440 run.builder.ensure(Rustc { stage: run.builder.top_stage, target: run.target });
443 /// Generates compiler documentation.
445 /// This will generate all documentation for compiler and dependencies.
446 /// Compiler documentation is distributed separately, so we make sure
447 /// we do not merge it with the other documentation from std, test and
448 /// proc_macros. This is largely just a wrapper around `cargo doc`.
449 fn run(self, builder: &Builder<'_>) {
450 let stage = self.stage;
451 let target = self.target;
452 builder.info(&format!("Documenting stage{} compiler ({})", stage, target));
454 // This is the intended out directory for compiler documentation.
455 let out = builder.compiler_doc_out(target);
456 t!(fs::create_dir_all(&out));
458 // Get the correct compiler for this stage.
459 let compiler = builder.compiler_for(stage, builder.config.build, target);
461 if !builder.config.compiler_docs {
462 builder.info("\tskipping - compiler/librustdoc docs disabled");
467 builder.ensure(compile::Rustc { compiler, target });
469 // We do not symlink to the same shared folder that already contains std library
470 // documentation from previous steps as we do not want to include that.
471 let out_dir = builder.stage_out(compiler, Mode::Rustc).join(target).join("doc");
472 t!(symlink_dir_force(&builder.config, &out, &out_dir));
474 // Build cargo command.
475 let mut cargo = builder.cargo(compiler, Mode::Rustc, target, "doc");
476 cargo.env("RUSTDOCFLAGS", "--document-private-items");
477 compile::rustc_cargo(builder, &mut cargo, target);
479 // Only include compiler crates, no dependencies of those, such as `libc`.
480 cargo.arg("--no-deps");
482 // Find dependencies for top level crates.
483 let mut compiler_crates = HashSet::new();
484 for root_crate in &["rustc_driver", "rustc_codegen_llvm", "rustc_codegen_ssa"] {
485 let interned_root_crate = INTERNER.intern_str(root_crate);
486 find_compiler_crates(builder, &interned_root_crate, &mut compiler_crates);
489 for krate in &compiler_crates {
490 // Create all crate output directories first to make sure rustdoc uses
492 // FIXME: Cargo should probably do this itself.
493 t!(fs::create_dir_all(out_dir.join(krate)));
494 cargo.arg("-p").arg(krate);
497 builder.run(&mut cargo.into());
501 fn find_compiler_crates(
502 builder: &Builder<'_>,
503 name: &Interned<String>,
504 crates: &mut HashSet<Interned<String>>,
506 // Add current crate.
507 crates.insert(*name);
509 // Look for dependencies.
510 for dep in builder.crates.get(name).unwrap().deps.iter() {
511 if builder.crates.get(dep).unwrap().is_local(builder) {
512 find_compiler_crates(builder, dep, crates);
517 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
520 target: Interned<String>,
523 impl Step for Rustdoc {
525 const DEFAULT: bool = true;
526 const ONLY_HOSTS: bool = true;
528 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
529 run.krate("rustdoc-tool")
532 fn make_run(run: RunConfig<'_>) {
533 run.builder.ensure(Rustdoc { stage: run.builder.top_stage, target: run.target });
536 /// Generates compiler documentation.
538 /// This will generate all documentation for compiler and dependencies.
539 /// Compiler documentation is distributed separately, so we make sure
540 /// we do not merge it with the other documentation from std, test and
541 /// proc_macros. This is largely just a wrapper around `cargo doc`.
542 fn run(self, builder: &Builder<'_>) {
543 let stage = self.stage;
544 let target = self.target;
545 builder.info(&format!("Documenting stage{} rustdoc ({})", stage, target));
547 // This is the intended out directory for compiler documentation.
548 let out = builder.compiler_doc_out(target);
549 t!(fs::create_dir_all(&out));
551 // Get the correct compiler for this stage.
552 let compiler = builder.compiler_for(stage, builder.config.build, target);
554 if !builder.config.compiler_docs {
555 builder.info("\tskipping - compiler/librustdoc docs disabled");
559 // Build rustc docs so that we generate relative links.
560 builder.ensure(Rustc { stage, target });
563 builder.ensure(tool::Rustdoc { compiler: compiler });
565 // Symlink compiler docs to the output directory of rustdoc documentation.
566 let out_dir = builder.stage_out(compiler, Mode::ToolRustc).join(target).join("doc");
567 t!(fs::create_dir_all(&out_dir));
568 t!(symlink_dir_force(&builder.config, &out, &out_dir));
570 // Build cargo command.
571 let mut cargo = prepare_tool_cargo(
582 // Only include compiler crates, no dependencies of those, such as `libc`.
583 cargo.arg("--no-deps");
584 cargo.arg("-p").arg("rustdoc");
586 cargo.env("RUSTDOCFLAGS", "--document-private-items");
587 builder.run(&mut cargo.into());
591 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
592 pub struct ErrorIndex {
593 target: Interned<String>,
596 impl Step for ErrorIndex {
598 const DEFAULT: bool = true;
599 const ONLY_HOSTS: bool = true;
601 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
602 let builder = run.builder;
603 run.path("src/tools/error_index_generator").default_condition(builder.config.docs)
606 fn make_run(run: RunConfig<'_>) {
607 run.builder.ensure(ErrorIndex { target: run.target });
610 /// Generates the HTML rendered error-index by running the
611 /// `error_index_generator` tool.
612 fn run(self, builder: &Builder<'_>) {
613 let target = self.target;
615 builder.info(&format!("Documenting error index ({})", target));
616 let out = builder.doc_out(target);
617 t!(fs::create_dir_all(&out));
618 let compiler = builder.compiler(2, builder.config.build);
619 let mut index = tool::ErrorIndex::command(builder, compiler);
621 index.arg(out.join("error-index.html"));
622 index.arg(crate::channel::CFG_RELEASE_NUM);
624 // FIXME: shouldn't have to pass this env var
625 index.env("CFG_BUILD", &builder.config.build);
627 builder.run(&mut index);
631 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]
632 pub struct UnstableBookGen {
633 target: Interned<String>,
636 impl Step for UnstableBookGen {
638 const DEFAULT: bool = true;
639 const ONLY_HOSTS: bool = true;
641 fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
642 let builder = run.builder;
643 run.path("src/tools/unstable-book-gen").default_condition(builder.config.docs)
646 fn make_run(run: RunConfig<'_>) {
647 run.builder.ensure(UnstableBookGen { target: run.target });
650 fn run(self, builder: &Builder<'_>) {
651 let target = self.target;
653 builder.info(&format!("Generating unstable book md files ({})", target));
654 let out = builder.md_doc_out(target).join("unstable-book");
655 builder.create_dir(&out);
656 builder.remove_dir(&out);
657 let mut cmd = builder.tool_cmd(Tool::UnstableBookGen);
658 cmd.arg(builder.src.join("src"));
661 builder.run(&mut cmd);
665 fn symlink_dir_force(config: &Config, src: &Path, dst: &Path) -> io::Result<()> {
669 if let Ok(m) = fs::symlink_metadata(dst) {
670 if m.file_type().is_dir() {
671 fs::remove_dir_all(dst)?;
673 // handle directory junctions on windows by falling back to
675 fs::remove_file(dst).or_else(|_| fs::remove_dir(dst))?;
679 symlink_dir(config, src, dst)