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.
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.
11 //! Documentation generation for rustbuild.
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.
17 //! Everything here is basically just a shim around calling either `rustbook` or
20 use std::fs::{self, File};
21 use std::io::prelude::*;
24 use std::process::Command;
26 use {Build, Compiler, Mode};
27 use util::{cp_r, symlink_dir};
28 use build_helper::up_to_date;
30 /// Invoke `rustbook` for `target` for the doc book `name`.
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);
39 /// Invoke `rustbook` for `target` for the doc book `name` from the `src` path.
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));
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) {
55 println!("Rustbook ({}) - {}", target, name);
56 let _ = fs::remove_dir_all(&out);
57 build.run(build.tool_cmd(&compiler, "rustbook")
64 /// Build the book and associated stuff.
68 /// * Book (first edition)
69 /// * Book (second edition)
72 pub fn book(build: &Build, target: &str, name: &str) {
73 // build book first edition
74 rustbook(build, target, &format!("{}/first-edition", name));
76 // build book second edition
77 rustbook(build, target, &format!("{}/second-edition", name));
79 // build the index page
80 let index = format!("{}/index.md", name);
81 println!("Documenting book index ({})", target);
82 invoke_rustdoc(build, target, &index);
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"))) {
88 let path = file.path();
89 let path = path.to_str().unwrap();
91 invoke_rustdoc(build, target, path);
95 fn invoke_rustdoc(build: &Build, target: &str, markdown: &str) {
96 let out = build.doc_out(target);
98 let compiler = Compiler::new(0, &build.config.build);
100 let path = build.src.join("src/doc").join(markdown);
102 let rustdoc = build.rustdoc(&compiler);
104 let favicon = build.src.join("src/doc/favicon.inc");
105 let footer = build.src.join("src/doc/footer.inc");
107 let version_input = build.src.join("src/doc/version_info.html.template");
108 let version_info = out.join("version_info.html");
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()));
119 let mut cmd = Command::new(&rustdoc);
121 build.add_rustc_lib_path(&compiler, &mut cmd);
123 let out = out.join("book");
125 t!(fs::copy(build.src.join("src/doc/rust.css"), out.join("rust.css")));
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/")
134 .arg("--markdown-css")
140 /// Generates all standalone documentation as compiled by the rustdoc in `stage`
141 /// for the `target` into `out`.
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.
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));
153 let compiler = Compiler::new(0, &build.config.build);
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")));
160 let version_input = build.src.join("src/doc/version_info.html.template");
161 let version_info = out.join("version_info.html");
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()));
172 for file in t!(fs::read_dir(build.src.join("src/doc"))) {
174 let path = file.path();
175 let filename = path.file_name().unwrap().to_str().unwrap();
176 if !filename.ends_with(".md") || filename == "README.md" {
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) {
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/")
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");
206 cmd.arg("--markdown-css").arg("rust.css");
212 /// Compile all standard library documentation.
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)
226 let out_dir = build.stage_out(&compiler, Mode::Libstd)
227 .join(target).join("doc");
228 let rustdoc = build.rustdoc(&compiler);
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.
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
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));
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());
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", "core", "std", "std_unicode"] {
258 cargo.arg("-p").arg(krate);
259 // Create all crate output directories first to make sure rustdoc uses
261 // FIXME: Cargo should probably do this itself.
262 t!(fs::create_dir_all(out_dir.join(krate)));
267 build.run(&mut cargo);
271 /// Compile all libtest documentation.
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)
285 let out_dir = build.stage_out(&compiler, Mode::Libtest)
286 .join(target).join("doc");
287 let rustdoc = build.rustdoc(&compiler);
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));
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);
301 /// Generate all compiler documentation.
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)
315 let out_dir = build.stage_out(&compiler, Mode::Librustc)
316 .join(target).join("doc");
317 let rustdoc = build.rustdoc(&compiler);
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));
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());
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");
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);
344 build.run(&mut cargo);
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");
357 index.arg(out.join("error-index.html"));
359 // FIXME: shouldn't have to pass this env var
360 index.env("CFG_BUILD", &build.config.build);
362 build.run(&mut index);
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"));
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));
383 // handle directory junctions on windows by falling back to
385 try!(fs::remove_file(dst).or_else(|_| {
391 symlink_dir(src, dst)