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::process::Command;
  23
  24 use {Build, Compiler, Mode};
  25 use util::{up_to_date, cp_r};
  26
  27 /// Invoke `rustbook` as compiled in `stage` for `target` for the doc book
  28 /// `name` into the `out` path.
  29 ///
  30 /// This will not actually generate any documentation if the documentation has
  31 /// already been generated.
  32 pub fn rustbook(build: &Build, target: &str, name: &str) {
  33     let out = build.doc_out(target);
  34     t!(fs::create_dir_all(&out));
  35
  36     let out = out.join(name);
  37     let compiler = Compiler::new(0, &build.config.build);
  38     let src = build.src.join("src/doc").join(name);
  39     let index = out.join("index.html");
  40     let rustbook = build.tool(&compiler, "rustbook");
  41     if up_to_date(&src, &index) && up_to_date(&rustbook, &index) {
  42         return
  43     }
  44     println!("Rustbook ({}) - {}", target, name);
  45     let _ = fs::remove_dir_all(&out);
  46     build.run(build.tool_cmd(&compiler, "rustbook")
  47                    .arg("build")
  48                    .arg(&src)
  49                    .arg(out));
  50 }
  51
  52 /// Generates all standalone documentation as compiled by the rustdoc in `stage`
  53 /// for the `target` into `out`.
  54 ///
  55 /// This will list all of `src/doc` looking for markdown files and appropriately
  56 /// perform transformations like substituting `VERSION`, `SHORT_HASH`, and
  57 /// `STAMP` alongw ith providing the various header/footer HTML we've cutomized.
  58 ///
  59 /// In the end, this is just a glorified wrapper around rustdoc!
  60 pub fn standalone(build: &Build, target: &str) {
  61     println!("Documenting standalone ({})", target);
  62     let out = build.doc_out(target);
  63     t!(fs::create_dir_all(&out));
  64
  65     let compiler = Compiler::new(0, &build.config.build);
  66
  67     let favicon = build.src.join("src/doc/favicon.inc");
  68     let footer = build.src.join("src/doc/footer.inc");
  69     let full_toc = build.src.join("src/doc/full-toc.inc");
  70     t!(fs::copy(build.src.join("src/doc/rust.css"), out.join("rust.css")));
  71
  72     let version_input = build.src.join("src/doc/version_info.html.template");
  73     let version_info = out.join("version_info.html");
  74
  75     if !up_to_date(&version_input, &version_info) {
  76         let mut info = String::new();
  77         t!(t!(File::open(&version_input)).read_to_string(&mut info));
  78         let blank = String::new();
  79         let short = build.short_ver_hash.as_ref().unwrap_or(&blank);
  80         let hash = build.ver_hash.as_ref().unwrap_or(&blank);
  81         let info = info.replace("VERSION", &build.release)
  82                        .replace("SHORT_HASH", short)
  83                        .replace("STAMP", hash);
  84         t!(t!(File::create(&version_info)).write_all(info.as_bytes()));
  85     }
  86
  87     for file in t!(fs::read_dir(build.src.join("src/doc"))) {
  88         let file = t!(file);
  89         let path = file.path();
  90         let filename = path.file_name().unwrap().to_str().unwrap();
  91         if !filename.ends_with(".md") || filename == "README.md" {
  92             continue
  93         }
  94
  95         let html = out.join(filename).with_extension("html");
  96         let rustdoc = build.rustdoc(&compiler);
  97         if up_to_date(&path, &html) &&
  98            up_to_date(&footer, &html) &&
  99            up_to_date(&favicon, &html) &&
 100            up_to_date(&full_toc, &html) &&
 101            up_to_date(&version_info, &html) &&
 102            up_to_date(&rustdoc, &html) {
 103             continue
 104         }
 105
 106         let mut cmd = Command::new(&rustdoc);
 107         build.add_rustc_lib_path(&compiler, &mut cmd);
 108         cmd.arg("--html-after-content").arg(&footer)
 109            .arg("--html-before-content").arg(&version_info)
 110            .arg("--html-in-header").arg(&favicon)
 111            .arg("--markdown-playground-url")
 112            .arg("https://play.rust-lang.org/")
 113            .arg("-o").arg(&out)
 114            .arg(&path);
 115
 116         if filename == "reference.md" {
 117            cmd.arg("--html-in-header").arg(&full_toc);
 118         }
 119
 120         if filename == "not_found.md" {
 121             cmd.arg("--markdown-no-toc")
 122                .arg("--markdown-css")
 123                .arg("https://doc.rust-lang.org/rust.css");
 124         } else {
 125             cmd.arg("--markdown-css").arg("rust.css");
 126         }
 127         build.run(&mut cmd);
 128     }
 129 }
 130
 131 /// Compile all standard library documentation.
 132 ///
 133 /// This will generate all documentation for the standard library and its
 134 /// dependencies. This is largely just a wrapper around `cargo doc`.
 135 pub fn std(build: &Build, stage: u32, target: &str) {
 136     println!("Documenting stage{} std ({})", stage, target);
 137     let out = build.doc_out(target);
 138     t!(fs::create_dir_all(&out));
 139     let compiler = Compiler::new(stage, &build.config.build);
 140     let compiler = if build.force_use_stage1(&compiler, target) {
 141         Compiler::new(1, compiler.host)
 142     } else {
 143         compiler
 144     };
 145     let out_dir = build.stage_out(&compiler, Mode::Libstd)
 146                        .join(target).join("doc");
 147     let rustdoc = build.rustdoc(&compiler);
 148
 149     build.clear_if_dirty(&out_dir, &rustdoc);
 150
 151     let mut cargo = build.cargo(&compiler, Mode::Libstd, target, "doc");
 152     cargo.arg("--manifest-path")
 153          .arg(build.src.join("src/rustc/std_shim/Cargo.toml"))
 154          .arg("--features").arg(build.std_features())
 155          .arg("--no-deps");
 156
 157     for krate in &["alloc", "collections", "core", "std", "std_unicode"] {
 158         cargo.arg("-p").arg(krate);
 159         // Create all crate output directories first to make sure rustdoc uses
 160         // relative links.
 161         // FIXME: Cargo should probably do this itself.
 162         t!(fs::create_dir_all(out_dir.join(krate)));
 163     }
 164
 165     build.run(&mut cargo);
 166     cp_r(&out_dir, &out)
 167 }
 168
 169 /// Compile all libtest documentation.
 170 ///
 171 /// This will generate all documentation for libtest and its dependencies. This
 172 /// is largely just a wrapper around `cargo doc`.
 173 pub fn test(build: &Build, stage: u32, target: &str) {
 174     println!("Documenting stage{} test ({})", stage, target);
 175     let out = build.doc_out(target);
 176     t!(fs::create_dir_all(&out));
 177     let compiler = Compiler::new(stage, &build.config.build);
 178     let compiler = if build.force_use_stage1(&compiler, target) {
 179         Compiler::new(1, compiler.host)
 180     } else {
 181         compiler
 182     };
 183     let out_dir = build.stage_out(&compiler, Mode::Libtest)
 184                        .join(target).join("doc");
 185     let rustdoc = build.rustdoc(&compiler);
 186
 187     build.clear_if_dirty(&out_dir, &rustdoc);
 188
 189     let mut cargo = build.cargo(&compiler, Mode::Libtest, target, "doc");
 190     cargo.arg("--manifest-path")
 191          .arg(build.src.join("src/rustc/test_shim/Cargo.toml"));
 192     build.run(&mut cargo);
 193     cp_r(&out_dir, &out)
 194 }
 195
 196 /// Generate all compiler documentation.
 197 ///
 198 /// This will generate all documentation for the compiler libraries and their
 199 /// dependencies. This is largely just a wrapper around `cargo doc`.
 200 pub fn rustc(build: &Build, stage: u32, target: &str) {
 201     println!("Documenting stage{} compiler ({})", stage, target);
 202     let out = build.doc_out(target);
 203     t!(fs::create_dir_all(&out));
 204     let compiler = Compiler::new(stage, &build.config.build);
 205     let compiler = if build.force_use_stage1(&compiler, target) {
 206         Compiler::new(1, compiler.host)
 207     } else {
 208         compiler
 209     };
 210     let out_dir = build.stage_out(&compiler, Mode::Librustc)
 211                        .join(target).join("doc");
 212     let rustdoc = build.rustdoc(&compiler);
 213     if !up_to_date(&rustdoc, &out_dir.join("rustc/index.html")) && out_dir.exists() {
 214         t!(fs::remove_dir_all(&out_dir));
 215     }
 216     let mut cargo = build.cargo(&compiler, Mode::Librustc, target, "doc");
 217     cargo.arg("--manifest-path")
 218          .arg(build.src.join("src/rustc/Cargo.toml"))
 219          .arg("--features").arg(build.rustc_features());
 220     build.run(&mut cargo);
 221     cp_r(&out_dir, &out)
 222 }
 223
 224 /// Generates the HTML rendered error-index by running the
 225 /// `error_index_generator` tool.
 226 pub fn error_index(build: &Build, target: &str) {
 227     println!("Documenting error index ({})", target);
 228     let out = build.doc_out(target);
 229     t!(fs::create_dir_all(&out));
 230     let compiler = Compiler::new(0, &build.config.build);
 231     let mut index = build.tool_cmd(&compiler, "error_index_generator");
 232     index.arg("html");
 233     index.arg(out.join("error-index.html"));
 234
 235     // FIXME: shouldn't have to pass this env var
 236     index.env("CFG_BUILD", &build.config.build);
 237
 238     build.run(&mut index);
 239 }