src/librustdoc/html/render/write_shared.rs

   1 use std::ffi::OsStr;
   2 use std::fmt::Write;
   3 use std::fs::{self, File};
   4 use std::io::prelude::*;
   5 use std::io::{self, BufReader};
   6 use std::lazy::SyncLazy as Lazy;
   7 use std::path::{Component, Path, PathBuf};
   8
   9 use itertools::Itertools;
  10 use rustc_data_structures::flock;
  11 use rustc_data_structures::fx::{FxHashMap, FxHashSet};
  12 use serde::Serialize;
  13
  14 use super::{collect_paths_for_type, ensure_trailing_slash, Context, BASIC_KEYWORDS};
  15 use crate::clean::Crate;
  16 use crate::config::RenderOptions;
  17 use crate::docfs::{DocFS, PathError};
  18 use crate::error::Error;
  19 use crate::formats::FormatRenderer;
  20 use crate::html::{layout, static_files};
  21
  22 crate static FILES_UNVERSIONED: Lazy<FxHashMap<&str, &[u8]>> = Lazy::new(|| {
  23     map! {
  24         "FiraSans-Regular.woff2" => static_files::fira_sans::REGULAR2,
  25         "FiraSans-Medium.woff2" => static_files::fira_sans::MEDIUM2,
  26         "FiraSans-Regular.woff" => static_files::fira_sans::REGULAR,
  27         "FiraSans-Medium.woff" => static_files::fira_sans::MEDIUM,
  28         "FiraSans-LICENSE.txt" => static_files::fira_sans::LICENSE,
  29         "SourceSerifPro-Regular.ttf.woff" => static_files::source_serif_pro::REGULAR,
  30         "SourceSerifPro-Bold.ttf.woff" => static_files::source_serif_pro::BOLD,
  31         "SourceSerifPro-It.ttf.woff" => static_files::source_serif_pro::ITALIC,
  32         "SourceSerifPro-LICENSE.md" => static_files::source_serif_pro::LICENSE,
  33         "SourceCodePro-Regular.ttf.woff" => static_files::source_code_pro::REGULAR,
  34         "SourceCodePro-Semibold.ttf.woff" => static_files::source_code_pro::SEMIBOLD,
  35         "SourceCodePro-It.ttf.woff" => static_files::source_code_pro::ITALIC,
  36         "SourceCodePro-LICENSE.txt" => static_files::source_code_pro::LICENSE,
  37         "LICENSE-MIT.txt" => static_files::LICENSE_MIT,
  38         "LICENSE-APACHE.txt" => static_files::LICENSE_APACHE,
  39         "COPYRIGHT.txt" => static_files::COPYRIGHT,
  40     }
  41 });
  42
  43 pub(super) fn write_shared(
  44     cx: &Context<'_>,
  45     krate: &Crate,
  46     search_index: String,
  47     options: &RenderOptions,
  48 ) -> Result<(), Error> {
  49     // Write out the shared files. Note that these are shared among all rustdoc
  50     // docs placed in the output directory, so this needs to be a synchronized
  51     // operation with respect to all other rustdocs running around.
  52     let lock_file = cx.dst.join(".lock");
  53     let _lock = try_err!(flock::Lock::new(&lock_file, true, true, true), &lock_file);
  54
  55     // Add all the static files. These may already exist, but we just
  56     // overwrite them anyway to make sure that they're fresh and up-to-date.
  57
  58     write_minify(
  59         &cx.shared.fs,
  60         cx.path("rustdoc.css"),
  61         static_files::RUSTDOC_CSS,
  62         options.enable_minification,
  63     )?;
  64     write_minify(
  65         &cx.shared.fs,
  66         cx.path("settings.css"),
  67         static_files::SETTINGS_CSS,
  68         options.enable_minification,
  69     )?;
  70     write_minify(
  71         &cx.shared.fs,
  72         cx.path("noscript.css"),
  73         static_files::NOSCRIPT_CSS,
  74         options.enable_minification,
  75     )?;
  76
  77     // To avoid "light.css" to be overwritten, we'll first run over the received themes and only
  78     // then we'll run over the "official" styles.
  79     let mut themes: FxHashSet<String> = FxHashSet::default();
  80
  81     for entry in &cx.shared.style_files {
  82         let theme = try_none!(try_none!(entry.path.file_stem(), &entry.path).to_str(), &entry.path);
  83         let extension =
  84             try_none!(try_none!(entry.path.extension(), &entry.path).to_str(), &entry.path);
  85
  86         // Handle the official themes
  87         match theme {
  88             "light" => write_minify(
  89                 &cx.shared.fs,
  90                 cx.path("light.css"),
  91                 static_files::themes::LIGHT,
  92                 options.enable_minification,
  93             )?,
  94             "dark" => write_minify(
  95                 &cx.shared.fs,
  96                 cx.path("dark.css"),
  97                 static_files::themes::DARK,
  98                 options.enable_minification,
  99             )?,
 100             "ayu" => write_minify(
 101                 &cx.shared.fs,
 102                 cx.path("ayu.css"),
 103                 static_files::themes::AYU,
 104                 options.enable_minification,
 105             )?,
 106             _ => {
 107                 // Handle added third-party themes
 108                 let content = try_err!(fs::read(&entry.path), &entry.path);
 109                 cx.shared
 110                     .fs
 111                     .write(cx.path(&format!("{}.{}", theme, extension)), content.as_slice())?;
 112             }
 113         };
 114
 115         themes.insert(theme.to_owned());
 116     }
 117
 118     let write = |p, c| cx.shared.fs.write(p, c);
 119     if (*cx.shared).layout.logo.is_empty() {
 120         write(cx.path("rust-logo.png"), static_files::RUST_LOGO)?;
 121     }
 122     if (*cx.shared).layout.favicon.is_empty() {
 123         write(cx.path("favicon.svg"), static_files::RUST_FAVICON_SVG)?;
 124         write(cx.path("favicon-16x16.png"), static_files::RUST_FAVICON_PNG_16)?;
 125         write(cx.path("favicon-32x32.png"), static_files::RUST_FAVICON_PNG_32)?;
 126     }
 127     write(cx.path("brush.svg"), static_files::BRUSH_SVG)?;
 128     write(cx.path("wheel.svg"), static_files::WHEEL_SVG)?;
 129     write(cx.path("down-arrow.svg"), static_files::DOWN_ARROW_SVG)?;
 130
 131     let mut themes: Vec<&String> = themes.iter().collect();
 132     themes.sort();
 133
 134     write_minify(
 135         &cx.shared.fs,
 136         cx.path("main.js"),
 137         &static_files::MAIN_JS.replace(
 138             "/* INSERT THEMES HERE */",
 139             &format!(" = {}", serde_json::to_string(&themes).unwrap()),
 140         ),
 141         options.enable_minification,
 142     )?;
 143     write_minify(
 144         &cx.shared.fs,
 145         cx.path("settings.js"),
 146         static_files::SETTINGS_JS,
 147         options.enable_minification,
 148     )?;
 149     if cx.shared.include_sources {
 150         write_minify(
 151             &cx.shared.fs,
 152             cx.path("source-script.js"),
 153             static_files::sidebar::SOURCE_SCRIPT,
 154             options.enable_minification,
 155         )?;
 156     }
 157
 158     {
 159         write_minify(
 160             &cx.shared.fs,
 161             cx.path("storage.js"),
 162             &format!(
 163                 "var resourcesSuffix = \"{}\";{}",
 164                 cx.shared.resource_suffix,
 165                 static_files::STORAGE_JS
 166             ),
 167             options.enable_minification,
 168         )?;
 169     }
 170
 171     if let Some(ref css) = cx.shared.layout.css_file_extension {
 172         let out = cx.path("theme.css");
 173         let buffer = try_err!(fs::read_to_string(css), css);
 174         if !options.enable_minification {
 175             cx.shared.fs.write(&out, &buffer)?;
 176         } else {
 177             write_minify(&cx.shared.fs, out, &buffer, options.enable_minification)?;
 178         }
 179     }
 180     write_minify(
 181         &cx.shared.fs,
 182         cx.path("normalize.css"),
 183         static_files::NORMALIZE_CSS,
 184         options.enable_minification,
 185     )?;
 186     for (file, contents) in &*FILES_UNVERSIONED {
 187         write(cx.dst.join(file), contents)?;
 188     }
 189
 190     fn collect(path: &Path, krate: &str, key: &str) -> io::Result<(Vec<String>, Vec<String>)> {
 191         let mut ret = Vec::new();
 192         let mut krates = Vec::new();
 193
 194         if path.exists() {
 195             let prefix = format!(r#"{}["{}"]"#, key, krate);
 196             for line in BufReader::new(File::open(path)?).lines() {
 197                 let line = line?;
 198                 if !line.starts_with(key) {
 199                     continue;
 200                 }
 201                 if line.starts_with(&prefix) {
 202                     continue;
 203                 }
 204                 ret.push(line.to_string());
 205                 krates.push(
 206                     line[key.len() + 2..]
 207                         .split('"')
 208                         .next()
 209                         .map(|s| s.to_owned())
 210                         .unwrap_or_else(String::new),
 211                 );
 212             }
 213         }
 214         Ok((ret, krates))
 215     }
 216
 217     fn collect_json(path: &Path, krate: &str) -> io::Result<(Vec<String>, Vec<String>)> {
 218         let mut ret = Vec::new();
 219         let mut krates = Vec::new();
 220
 221         if path.exists() {
 222             let prefix = format!("\"{}\"", krate);
 223             for line in BufReader::new(File::open(path)?).lines() {
 224                 let line = line?;
 225                 if !line.starts_with('"') {
 226                     continue;
 227                 }
 228                 if line.starts_with(&prefix) {
 229                     continue;
 230                 }
 231                 if line.ends_with(",\\") {
 232                     ret.push(line[..line.len() - 2].to_string());
 233                 } else {
 234                     // Ends with "\\" (it's the case for the last added crate line)
 235                     ret.push(line[..line.len() - 1].to_string());
 236                 }
 237                 krates.push(
 238                     line.split('"')
 239                         .find(|s| !s.is_empty())
 240                         .map(|s| s.to_owned())
 241                         .unwrap_or_else(String::new),
 242                 );
 243             }
 244         }
 245         Ok((ret, krates))
 246     }
 247
 248     use std::ffi::OsString;
 249
 250     #[derive(Debug)]
 251     struct Hierarchy {
 252         elem: OsString,
 253         children: FxHashMap<OsString, Hierarchy>,
 254         elems: FxHashSet<OsString>,
 255     }
 256
 257     impl Hierarchy {
 258         fn new(elem: OsString) -> Hierarchy {
 259             Hierarchy { elem, children: FxHashMap::default(), elems: FxHashSet::default() }
 260         }
 261
 262         fn to_json_string(&self) -> String {
 263             let mut subs: Vec<&Hierarchy> = self.children.values().collect();
 264             subs.sort_unstable_by(|a, b| a.elem.cmp(&b.elem));
 265             let mut files = self
 266                 .elems
 267                 .iter()
 268                 .map(|s| format!("\"{}\"", s.to_str().expect("invalid osstring conversion")))
 269                 .collect::<Vec<_>>();
 270             files.sort_unstable();
 271             let subs = subs.iter().map(|s| s.to_json_string()).collect::<Vec<_>>().join(",");
 272             let dirs =
 273                 if subs.is_empty() { String::new() } else { format!(",\"dirs\":[{}]", subs) };
 274             let files = files.join(",");
 275             let files =
 276                 if files.is_empty() { String::new() } else { format!(",\"files\":[{}]", files) };
 277             format!(
 278                 "{{\"name\":\"{name}\"{dirs}{files}}}",
 279                 name = self.elem.to_str().expect("invalid osstring conversion"),
 280                 dirs = dirs,
 281                 files = files
 282             )
 283         }
 284     }
 285
 286     if cx.shared.include_sources {
 287         let mut hierarchy = Hierarchy::new(OsString::new());
 288         for source in cx
 289             .shared
 290             .local_sources
 291             .iter()
 292             .filter_map(|p| p.0.strip_prefix(&cx.shared.src_root).ok())
 293         {
 294             let mut h = &mut hierarchy;
 295             let mut elems = source
 296                 .components()
 297                 .filter_map(|s| match s {
 298                     Component::Normal(s) => Some(s.to_owned()),
 299                     _ => None,
 300                 })
 301                 .peekable();
 302             loop {
 303                 let cur_elem = elems.next().expect("empty file path");
 304                 if elems.peek().is_none() {
 305                     h.elems.insert(cur_elem);
 306                     break;
 307                 } else {
 308                     let e = cur_elem.clone();
 309                     h = h.children.entry(cur_elem.clone()).or_insert_with(|| Hierarchy::new(e));
 310                 }
 311             }
 312         }
 313
 314         let dst = cx.dst.join(&format!("source-files{}.js", cx.shared.resource_suffix));
 315         let (mut all_sources, _krates) =
 316             try_err!(collect(&dst, &krate.name.as_str(), "sourcesIndex"), &dst);
 317         all_sources.push(format!(
 318             "sourcesIndex[\"{}\"] = {};",
 319             &krate.name,
 320             hierarchy.to_json_string()
 321         ));
 322         all_sources.sort();
 323         let v = format!(
 324             "var N = null;var sourcesIndex = {{}};\n{}\ncreateSourceSidebar();\n",
 325             all_sources.join("\n")
 326         );
 327         cx.shared.fs.write(&dst, v.as_bytes())?;
 328     }
 329
 330     // Update the search index and crate list.
 331     let dst = cx.dst.join(&format!("search-index{}.js", cx.shared.resource_suffix));
 332     let (mut all_indexes, mut krates) = try_err!(collect_json(&dst, &krate.name.as_str()), &dst);
 333     all_indexes.push(search_index);
 334     krates.push(krate.name.to_string());
 335     krates.sort();
 336
 337     // Sort the indexes by crate so the file will be generated identically even
 338     // with rustdoc running in parallel.
 339     all_indexes.sort();
 340     {
 341         let mut v = String::from("var searchIndex = JSON.parse('{\\\n");
 342         v.push_str(&all_indexes.join(",\\\n"));
 343         v.push_str("\\\n}');\ninitSearch(searchIndex);");
 344         cx.shared.fs.write(&dst, &v)?;
 345     }
 346
 347     let crate_list_dst = cx.dst.join(&format!("crates{}.js", cx.shared.resource_suffix));
 348     let crate_list =
 349         format!("window.ALL_CRATES = [{}];", krates.iter().map(|k| format!("\"{}\"", k)).join(","));
 350     cx.shared.fs.write(&crate_list_dst, &crate_list)?;
 351
 352     if options.enable_index_page {
 353         if let Some(index_page) = options.index_page.clone() {
 354             let mut md_opts = options.clone();
 355             md_opts.output = cx.dst.clone();
 356             md_opts.external_html = (*cx.shared).layout.external_html.clone();
 357
 358             crate::markdown::render(&index_page, md_opts, cx.shared.edition)
 359                 .map_err(|e| Error::new(e, &index_page))?;
 360         } else {
 361             let dst = cx.dst.join("index.html");
 362             let page = layout::Page {
 363                 title: "Index of crates",
 364                 css_class: "mod",
 365                 root_path: "./",
 366                 static_root_path: cx.shared.static_root_path.as_deref(),
 367                 description: "List of crates",
 368                 keywords: BASIC_KEYWORDS,
 369                 resource_suffix: &cx.shared.resource_suffix,
 370                 extra_scripts: &[],
 371                 static_extra_scripts: &[],
 372             };
 373
 374             let content = format!(
 375                 "<h1 class=\"fqn\">\
 376                      <span class=\"in-band\">List of all crates</span>\
 377                 </h1><ul class=\"crate mod\">{}</ul>",
 378                 krates
 379                     .iter()
 380                     .map(|s| {
 381                         format!(
 382                             "<li><a class=\"crate mod\" href=\"{}index.html\">{}</a></li>",
 383                             ensure_trailing_slash(s),
 384                             s
 385                         )
 386                     })
 387                     .collect::<String>()
 388             );
 389             let v = layout::render(&cx.shared.layout, &page, "", content, &cx.shared.style_files);
 390             cx.shared.fs.write(&dst, v.as_bytes())?;
 391         }
 392     }
 393
 394     // Update the list of all implementors for traits
 395     let dst = cx.dst.join("implementors");
 396     for (&did, imps) in &cx.cache.implementors {
 397         // Private modules can leak through to this phase of rustdoc, which
 398         // could contain implementations for otherwise private types. In some
 399         // rare cases we could find an implementation for an item which wasn't
 400         // indexed, so we just skip this step in that case.
 401         //
 402         // FIXME: this is a vague explanation for why this can't be a `get`, in
 403         //        theory it should be...
 404         let &(ref remote_path, remote_item_type) = match cx.cache.paths.get(&did) {
 405             Some(p) => p,
 406             None => match cx.cache.external_paths.get(&did) {
 407                 Some(p) => p,
 408                 None => continue,
 409             },
 410         };
 411
 412         #[derive(Serialize)]
 413         struct Implementor {
 414             text: String,
 415             synthetic: bool,
 416             types: Vec<String>,
 417         }
 418
 419         let implementors = imps
 420             .iter()
 421             .filter_map(|imp| {
 422                 // If the trait and implementation are in the same crate, then
 423                 // there's no need to emit information about it (there's inlining
 424                 // going on). If they're in different crates then the crate defining
 425                 // the trait will be interested in our implementation.
 426                 //
 427                 // If the implementation is from another crate then that crate
 428                 // should add it.
 429                 if imp.impl_item.def_id.krate == did.krate || !imp.impl_item.def_id.is_local() {
 430                     None
 431                 } else {
 432                     Some(Implementor {
 433                         text: imp.inner_impl().print(cx.cache(), false).to_string(),
 434                         synthetic: imp.inner_impl().synthetic,
 435                         types: collect_paths_for_type(imp.inner_impl().for_.clone(), cx.cache()),
 436                     })
 437                 }
 438             })
 439             .collect::<Vec<_>>();
 440
 441         // Only create a js file if we have impls to add to it. If the trait is
 442         // documented locally though we always create the file to avoid dead
 443         // links.
 444         if implementors.is_empty() && !cx.cache.paths.contains_key(&did) {
 445             continue;
 446         }
 447
 448         let implementors = format!(
 449             r#"implementors["{}"] = {};"#,
 450             krate.name,
 451             serde_json::to_string(&implementors).unwrap()
 452         );
 453
 454         let mut mydst = dst.clone();
 455         for part in &remote_path[..remote_path.len() - 1] {
 456             mydst.push(part);
 457         }
 458         cx.shared.ensure_dir(&mydst)?;
 459         mydst.push(&format!("{}.{}.js", remote_item_type, remote_path[remote_path.len() - 1]));
 460
 461         let (mut all_implementors, _) =
 462             try_err!(collect(&mydst, &krate.name.as_str(), "implementors"), &mydst);
 463         all_implementors.push(implementors);
 464         // Sort the implementors by crate so the file will be generated
 465         // identically even with rustdoc running in parallel.
 466         all_implementors.sort();
 467
 468         let mut v = String::from("(function() {var implementors = {};\n");
 469         for implementor in &all_implementors {
 470             writeln!(v, "{}", *implementor).unwrap();
 471         }
 472         v.push_str(
 473             "if (window.register_implementors) {\
 474                  window.register_implementors(implementors);\
 475              } else {\
 476                  window.pending_implementors = implementors;\
 477              }",
 478         );
 479         v.push_str("})()");
 480         cx.shared.fs.write(&mydst, &v)?;
 481     }
 482     Ok(())
 483 }
 484
 485 fn write_minify(
 486     fs: &DocFS,
 487     dst: PathBuf,
 488     contents: &str,
 489     enable_minification: bool,
 490 ) -> Result<(), Error> {
 491     if enable_minification {
 492         if dst.extension() == Some(&OsStr::new("css")) {
 493             let res = try_none!(minifier::css::minify(contents).ok(), &dst);
 494             fs.write(dst, res.as_bytes())
 495         } else {
 496             fs.write(dst, minifier::js::minify(contents).as_bytes())
 497         }
 498     } else {
 499         fs.write(dst, contents.as_bytes())
 500     }
 501 }