src/bootstrap/doc.rs

   1 // Copyright 2016 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 //! Documentation generation for rustbuild.
  12 //!
  13 //! This module implements generation for all bits and pieces of documentation
  14 //! for the Rust project. This notably includes suites like the rust book, the
  15 //! nomicon, standalone documentation, etc.
  16 //!
  17 //! Everything here is basically just a shim around calling either `rustbook` or
  18 //! `rustdoc`.
  19
  20 use std::fs::{self, File};
  21 use std::io::prelude::*;
  22 use std::io;
  23 use std::path::Path;
  24 use std::process::Command;
  25
  26 use {Build, Compiler, Mode};
  27 use util::{cp_r, symlink_dir};
  28 use build_helper::up_to_date;
  29
  30 /// Invoke `rustbook` for `target` for the doc book `name`.
  31 ///
  32 /// This will not actually generate any documentation if the documentation has
  33 /// already been generated.
  34 pub fn rustbook(build: &Build, target: &str, name: &str) {
  35     let src = build.src.join("src/doc");
  36     rustbook_src(build, target, name, &src);
  37 }
  38
  39 /// Invoke `rustbook` for `target` for the doc book `name` from the `src` path.
  40 ///
  41 /// This will not actually generate any documentation if the documentation has
  42 /// already been generated.
  43 pub fn rustbook_src(build: &Build, target: &str, name: &str, src: &Path) {
  44     let out = build.doc_out(target);
  45     t!(fs::create_dir_all(&out));
  46
  47     let out = out.join(name);
  48     let compiler = Compiler::new(0, &build.config.build);
  49     let src = src.join(name);
  50     let index = out.join("index.html");
  51     let rustbook = build.tool(&compiler, "rustbook");
  52     if up_to_date(&src, &index) && up_to_date(&rustbook, &index) {
  53         return
  54     }
  55     println!("Rustbook ({}) - {}", target, name);
  56     let _ = fs::remove_dir_all(&out);
  57     build.run(build.tool_cmd(&compiler, "rustbook")
  58                    .arg("build")
  59                    .arg(&src)
  60                    .arg("-d")
  61                    .arg(out));
  62 }
  63
  64 /// Build the book and associated stuff.
  65 ///
  66 /// We need to build:
  67 ///
  68 /// * Book (first edition)
  69 /// * Book (second edition)
  70 /// * Index page
  71 /// * Redirect pages
  72 pub fn book(build: &Build, target: &str, name: &str) {
  73     // build book first edition
  74     rustbook(build, target, &format!("{}/first-edition", name));
  75
  76     // build book second edition
  77     rustbook(build, target, &format!("{}/second-edition", name));
  78
  79     // build the index page
  80     let index = format!("{}/index.md", name);
  81     println!("Documenting book index ({})", target);
  82     invoke_rustdoc(build, target, &index);
  83
  84     // build the redirect pages
  85     println!("Documenting book redirect pages ({})", target);
  86     for file in t!(fs::read_dir(build.src.join("src/doc/book/redirects"))) {
  87         let file = t!(file);
  88         let path = file.path();
  89         let path = path.to_str().unwrap();
  90
  91         invoke_rustdoc(build, target, path);
  92     }
  93 }
  94
  95 fn invoke_rustdoc(build: &Build, target: &str, markdown: &str) {
  96     let out = build.doc_out(target);
  97
  98     let compiler = Compiler::new(0, &build.config.build);
  99
 100     let path = build.src.join("src/doc").join(markdown);
 101
 102     let rustdoc = build.rustdoc(&compiler);
 103
 104     let favicon = build.src.join("src/doc/favicon.inc");
 105     let footer = build.src.join("src/doc/footer.inc");
 106
 107     let version_input = build.src.join("src/doc/version_info.html.template");
 108     let version_info = out.join("version_info.html");
 109
 110     if !up_to_date(&version_input, &version_info) {
 111         let mut info = String::new();
 112         t!(t!(File::open(&version_input)).read_to_string(&mut info));
 113         let info = info.replace("VERSION", &build.rust_release())
 114                        .replace("SHORT_HASH", build.rust_info.sha_short().unwrap_or(""))
 115                        .replace("STAMP", build.rust_info.sha().unwrap_or(""));
 116         t!(t!(File::create(&version_info)).write_all(info.as_bytes()));
 117     }
 118
 119     let mut cmd = Command::new(&rustdoc);
 120
 121     build.add_rustc_lib_path(&compiler, &mut cmd);
 122
 123     let out = out.join("book");
 124
 125     t!(fs::copy(build.src.join("src/doc/rust.css"), out.join("rust.css")));
 126
 127     cmd.arg("--html-after-content").arg(&footer)
 128         .arg("--html-before-content").arg(&version_info)
 129         .arg("--html-in-header").arg(&favicon)
 130         .arg("--markdown-playground-url")
 131         .arg("https://play.rust-lang.org/")
 132         .arg("-o").arg(&out)
 133         .arg(&path)
 134         .arg("--markdown-css")
 135         .arg("rust.css");
 136
 137     build.run(&mut cmd);
 138 }
 139
 140 /// Generates all standalone documentation as compiled by the rustdoc in `stage`
 141 /// for the `target` into `out`.
 142 ///
 143 /// This will list all of `src/doc` looking for markdown files and appropriately
 144 /// perform transformations like substituting `VERSION`, `SHORT_HASH`, and
 145 /// `STAMP` alongw ith providing the various header/footer HTML we've cutomized.
 146 ///
 147 /// In the end, this is just a glorified wrapper around rustdoc!
 148 pub fn standalone(build: &Build, target: &str) {
 149     println!("Documenting standalone ({})", target);
 150     let out = build.doc_out(target);
 151     t!(fs::create_dir_all(&out));
 152
 153     let compiler = Compiler::new(0, &build.config.build);
 154
 155     let favicon = build.src.join("src/doc/favicon.inc");
 156     let footer = build.src.join("src/doc/footer.inc");
 157     let full_toc = build.src.join("src/doc/full-toc.inc");
 158     t!(fs::copy(build.src.join("src/doc/rust.css"), out.join("rust.css")));
 159
 160     let version_input = build.src.join("src/doc/version_info.html.template");
 161     let version_info = out.join("version_info.html");
 162
 163     if !up_to_date(&version_input, &version_info) {
 164         let mut info = String::new();
 165         t!(t!(File::open(&version_input)).read_to_string(&mut info));
 166         let info = info.replace("VERSION", &build.rust_release())
 167                        .replace("SHORT_HASH", build.rust_info.sha_short().unwrap_or(""))
 168                        .replace("STAMP", build.rust_info.sha().unwrap_or(""));
 169         t!(t!(File::create(&version_info)).write_all(info.as_bytes()));
 170     }
 171
 172     for file in t!(fs::read_dir(build.src.join("src/doc"))) {
 173         let file = t!(file);
 174         let path = file.path();
 175         let filename = path.file_name().unwrap().to_str().unwrap();
 176         if !filename.ends_with(".md") || filename == "README.md" {
 177             continue
 178         }
 179
 180         let html = out.join(filename).with_extension("html");
 181         let rustdoc = build.rustdoc(&compiler);
 182         if up_to_date(&path, &html) &&
 183            up_to_date(&footer, &html) &&
 184            up_to_date(&favicon, &html) &&
 185            up_to_date(&full_toc, &html) &&
 186            up_to_date(&version_info, &html) &&
 187            up_to_date(&rustdoc, &html) {
 188             continue
 189         }
 190
 191         let mut cmd = Command::new(&rustdoc);
 192         build.add_rustc_lib_path(&compiler, &mut cmd);
 193         cmd.arg("--html-after-content").arg(&footer)
 194            .arg("--html-before-content").arg(&version_info)
 195            .arg("--html-in-header").arg(&favicon)
 196            .arg("--markdown-playground-url")
 197            .arg("https://play.rust-lang.org/")
 198            .arg("-o").arg(&out)
 199            .arg(&path);
 200
 201         if filename == "not_found.md" {
 202             cmd.arg("--markdown-no-toc")
 203                .arg("--markdown-css")
 204                .arg("https://doc.rust-lang.org/rust.css");
 205         } else {
 206             cmd.arg("--markdown-css").arg("rust.css");
 207         }
 208         build.run(&mut cmd);
 209     }
 210 }
 211
 212 /// Compile all standard library documentation.
 213 ///
 214 /// This will generate all documentation for the standard library and its
 215 /// dependencies. This is largely just a wrapper around `cargo doc`.
 216 pub fn std(build: &Build, stage: u32, target: &str) {
 217     println!("Documenting stage{} std ({})", stage, target);
 218     let out = build.doc_out(target);
 219     t!(fs::create_dir_all(&out));
 220     let compiler = Compiler::new(stage, &build.config.build);
 221     let compiler = if build.force_use_stage1(&compiler, target) {
 222         Compiler::new(1, compiler.host)
 223     } else {
 224         compiler
 225     };
 226     let out_dir = build.stage_out(&compiler, Mode::Libstd)
 227                        .join(target).join("doc");
 228     let rustdoc = build.rustdoc(&compiler);
 229
 230     // Here what we're doing is creating a *symlink* (directory junction on
 231     // Windows) to the final output location. This is not done as an
 232     // optimization but rather for correctness. We've got three trees of
 233     // documentation, one for std, one for test, and one for rustc. It's then
 234     // our job to merge them all together.
 235     //
 236     // Unfortunately rustbuild doesn't know nearly as well how to merge doc
 237     // trees as rustdoc does itself, so instead of actually having three
 238     // separate trees we just have rustdoc output to the same location across
 239     // all of them.
 240     //
 241     // This way rustdoc generates output directly into the output, and rustdoc
 242     // will also directly handle merging.
 243     let my_out = build.crate_doc_out(target);
 244     build.clear_if_dirty(&my_out, &rustdoc);
 245     t!(symlink_dir_force(&my_out, &out_dir));
 246
 247     let mut cargo = build.cargo(&compiler, Mode::Libstd, target, "doc");
 248     cargo.arg("--manifest-path")
 249          .arg(build.src.join("src/libstd/Cargo.toml"))
 250          .arg("--features").arg(build.std_features());
 251
 252     // We don't want to build docs for internal std dependencies unless
 253     // in compiler-docs mode. When not in that mode, we whitelist the crates
 254     // for which docs must be built.
 255     if !build.config.compiler_docs {
 256         cargo.arg("--no-deps");
 257         for krate in &["alloc", "collections", "core", "std", "std_unicode"] {
 258             cargo.arg("-p").arg(krate);
 259             // Create all crate output directories first to make sure rustdoc uses
 260             // relative links.
 261             // FIXME: Cargo should probably do this itself.
 262             t!(fs::create_dir_all(out_dir.join(krate)));
 263         }
 264     }
 265
 266
 267     build.run(&mut cargo);
 268     cp_r(&my_out, &out);
 269 }
 270
 271 /// Compile all libtest documentation.
 272 ///
 273 /// This will generate all documentation for libtest and its dependencies. This
 274 /// is largely just a wrapper around `cargo doc`.
 275 pub fn test(build: &Build, stage: u32, target: &str) {
 276     println!("Documenting stage{} test ({})", stage, target);
 277     let out = build.doc_out(target);
 278     t!(fs::create_dir_all(&out));
 279     let compiler = Compiler::new(stage, &build.config.build);
 280     let compiler = if build.force_use_stage1(&compiler, target) {
 281         Compiler::new(1, compiler.host)
 282     } else {
 283         compiler
 284     };
 285     let out_dir = build.stage_out(&compiler, Mode::Libtest)
 286                        .join(target).join("doc");
 287     let rustdoc = build.rustdoc(&compiler);
 288
 289     // See docs in std above for why we symlink
 290     let my_out = build.crate_doc_out(target);
 291     build.clear_if_dirty(&my_out, &rustdoc);
 292     t!(symlink_dir_force(&my_out, &out_dir));
 293
 294     let mut cargo = build.cargo(&compiler, Mode::Libtest, target, "doc");
 295     cargo.arg("--manifest-path")
 296          .arg(build.src.join("src/libtest/Cargo.toml"));
 297     build.run(&mut cargo);
 298     cp_r(&my_out, &out);
 299 }
 300
 301 /// Generate all compiler documentation.
 302 ///
 303 /// This will generate all documentation for the compiler libraries and their
 304 /// dependencies. This is largely just a wrapper around `cargo doc`.
 305 pub fn rustc(build: &Build, stage: u32, target: &str) {
 306     println!("Documenting stage{} compiler ({})", stage, target);
 307     let out = build.doc_out(target);
 308     t!(fs::create_dir_all(&out));
 309     let compiler = Compiler::new(stage, &build.config.build);
 310     let compiler = if build.force_use_stage1(&compiler, target) {
 311         Compiler::new(1, compiler.host)
 312     } else {
 313         compiler
 314     };
 315     let out_dir = build.stage_out(&compiler, Mode::Librustc)
 316                        .join(target).join("doc");
 317     let rustdoc = build.rustdoc(&compiler);
 318
 319     // See docs in std above for why we symlink
 320     let my_out = build.crate_doc_out(target);
 321     build.clear_if_dirty(&my_out, &rustdoc);
 322     t!(symlink_dir_force(&my_out, &out_dir));
 323
 324     let mut cargo = build.cargo(&compiler, Mode::Librustc, target, "doc");
 325     cargo.arg("--manifest-path")
 326          .arg(build.src.join("src/rustc/Cargo.toml"))
 327          .arg("--features").arg(build.rustc_features());
 328
 329     if build.config.compiler_docs {
 330         // src/rustc/Cargo.toml contains bin crates called rustc and rustdoc
 331         // which would otherwise overwrite the docs for the real rustc and
 332         // rustdoc lib crates.
 333         cargo.arg("-p").arg("rustc_driver")
 334              .arg("-p").arg("rustdoc");
 335     } else {
 336         // Like with libstd above if compiler docs aren't enabled then we're not
 337         // documenting internal dependencies, so we have a whitelist.
 338         cargo.arg("--no-deps");
 339         for krate in &["proc_macro"] {
 340             cargo.arg("-p").arg(krate);
 341         }
 342     }
 343
 344     build.run(&mut cargo);
 345     cp_r(&my_out, &out);
 346 }
 347
 348 /// Generates the HTML rendered error-index by running the
 349 /// `error_index_generator` tool.
 350 pub fn error_index(build: &Build, target: &str) {
 351     println!("Documenting error index ({})", target);
 352     let out = build.doc_out(target);
 353     t!(fs::create_dir_all(&out));
 354     let compiler = Compiler::new(0, &build.config.build);
 355     let mut index = build.tool_cmd(&compiler, "error_index_generator");
 356     index.arg("html");
 357     index.arg(out.join("error-index.html"));
 358
 359     // FIXME: shouldn't have to pass this env var
 360     index.env("CFG_BUILD", &build.config.build);
 361
 362     build.run(&mut index);
 363 }
 364
 365 pub fn unstable_book_gen(build: &Build, target: &str) {
 366     println!("Generating unstable book md files ({})", target);
 367     let out = build.md_doc_out(target).join("unstable-book");
 368     t!(fs::create_dir_all(&out));
 369     t!(fs::remove_dir_all(&out));
 370     let compiler = Compiler::new(0, &build.config.build);
 371     let mut cmd = build.tool_cmd(&compiler, "unstable-book-gen");
 372     cmd.arg(build.src.join("src"));
 373     cmd.arg(out);
 374
 375     build.run(&mut cmd);
 376 }
 377
 378 fn symlink_dir_force(src: &Path, dst: &Path) -> io::Result<()> {
 379     if let Ok(m) = fs::symlink_metadata(dst) {
 380         if m.file_type().is_dir() {
 381             try!(fs::remove_dir_all(dst));
 382         } else {
 383             // handle directory junctions on windows by falling back to
 384             // `remove_dir`.
 385             try!(fs::remove_file(dst).or_else(|_| {
 386                 fs::remove_dir(dst)
 387             }));
 388         }
 389     }
 390
 391     symlink_dir(src, dst)
 392 }