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