src/librustdoc/html/render/context.rs

   1 use std::cell::RefCell;
   2 use std::collections::BTreeMap;
   3 use std::io;
   4 use std::path::PathBuf;
   5 use std::rc::Rc;
   6 use std::sync::mpsc::channel;
   7
   8 use rustc_data_structures::fx::FxHashMap;
   9 use rustc_hir::def_id::{DefId, LOCAL_CRATE};
  10 use rustc_middle::ty::TyCtxt;
  11 use rustc_session::Session;
  12 use rustc_span::edition::Edition;
  13 use rustc_span::source_map::FileName;
  14 use rustc_span::symbol::sym;
  15
  16 use super::cache::{build_index, ExternalLocation};
  17 use super::print_item::{full_path, item_path, print_item};
  18 use super::write_shared::write_shared;
  19 use super::{
  20     print_sidebar, settings, AllTypes, NameDoc, SharedContext, StylePath, BASIC_KEYWORDS,
  21     CURRENT_DEPTH, INITIAL_IDS,
  22 };
  23
  24 use crate::clean::{self, AttributesExt};
  25 use crate::config::RenderOptions;
  26 use crate::docfs::{DocFS, PathError};
  27 use crate::error::Error;
  28 use crate::formats::cache::Cache;
  29 use crate::formats::item_type::ItemType;
  30 use crate::formats::FormatRenderer;
  31 use crate::html::escape::Escape;
  32 use crate::html::format::Buffer;
  33 use crate::html::markdown::{self, plain_text_summary, ErrorCodes, IdMap};
  34 use crate::html::{layout, sources};
  35
  36 /// Major driving force in all rustdoc rendering. This contains information
  37 /// about where in the tree-like hierarchy rendering is occurring and controls
  38 /// how the current page is being rendered.
  39 ///
  40 /// It is intended that this context is a lightweight object which can be fairly
  41 /// easily cloned because it is cloned per work-job (about once per item in the
  42 /// rustdoc tree).
  43 crate struct Context<'tcx> {
  44     /// Current hierarchy of components leading down to what's currently being
  45     /// rendered
  46     pub(super) current: Vec<String>,
  47     /// The current destination folder of where HTML artifacts should be placed.
  48     /// This changes as the context descends into the module hierarchy.
  49     pub(super) dst: PathBuf,
  50     /// A flag, which when `true`, will render pages which redirect to the
  51     /// real location of an item. This is used to allow external links to
  52     /// publicly reused items to redirect to the right location.
  53     pub(super) render_redirect_pages: bool,
  54     /// The map used to ensure all generated 'id=' attributes are unique.
  55     pub(super) id_map: RefCell<IdMap>,
  56     /// Tracks section IDs for `Deref` targets so they match in both the main
  57     /// body and the sidebar.
  58     pub(super) deref_id_map: RefCell<FxHashMap<DefId, String>>,
  59     /// Shared mutable state.
  60     ///
  61     /// Issue for improving the situation: [#82381][]
  62     ///
  63     /// [#82381]: https://github.com/rust-lang/rust/issues/82381
  64     pub(super) shared: Rc<SharedContext<'tcx>>,
  65     /// The [`Cache`] used during rendering.
  66     ///
  67     /// Ideally the cache would be in [`SharedContext`], but it's mutated
  68     /// between when the `SharedContext` is created and when `Context`
  69     /// is created, so more refactoring would be needed.
  70     ///
  71     /// It's immutable once in `Context`, so it's not as bad that it's not in
  72     /// `SharedContext`.
  73     // FIXME: move `cache` to `SharedContext`
  74     pub(super) cache: Rc<Cache>,
  75 }
  76
  77 // `Context` is cloned a lot, so we don't want the size to grow unexpectedly.
  78 #[cfg(target_arch = "x86_64")]
  79 rustc_data_structures::static_assert_size!(Context<'_>, 152);
  80
  81 impl<'tcx> Context<'tcx> {
  82     pub(super) fn path(&self, filename: &str) -> PathBuf {
  83         // We use splitn vs Path::extension here because we might get a filename
  84         // like `style.min.css` and we want to process that into
  85         // `style-suffix.min.css`.  Path::extension would just return `css`
  86         // which would result in `style.min-suffix.css` which isn't what we
  87         // want.
  88         let (base, ext) = filename.split_once('.').unwrap();
  89         let filename = format!("{}{}.{}", base, self.shared.resource_suffix, ext);
  90         self.dst.join(&filename)
  91     }
  92
  93     pub(super) fn tcx(&self) -> TyCtxt<'tcx> {
  94         self.shared.tcx
  95     }
  96
  97     fn sess(&self) -> &'tcx Session {
  98         &self.shared.tcx.sess
  99     }
 100
 101     pub(super) fn derive_id(&self, id: String) -> String {
 102         let mut map = self.id_map.borrow_mut();
 103         map.derive(id)
 104     }
 105
 106     /// String representation of how to get back to the root path of the 'doc/'
 107     /// folder in terms of a relative URL.
 108     pub(super) fn root_path(&self) -> String {
 109         "../".repeat(self.current.len())
 110     }
 111
 112     fn render_item(&self, it: &clean::Item, pushname: bool) -> String {
 113         // A little unfortunate that this is done like this, but it sure
 114         // does make formatting *a lot* nicer.
 115         CURRENT_DEPTH.with(|slot| {
 116             slot.set(self.current.len());
 117         });
 118
 119         let mut title = if it.is_primitive() || it.is_keyword() {
 120             // No need to include the namespace for primitive types and keywords
 121             String::new()
 122         } else {
 123             self.current.join("::")
 124         };
 125         if pushname {
 126             if !title.is_empty() {
 127                 title.push_str("::");
 128             }
 129             title.push_str(&it.name.unwrap().as_str());
 130         }
 131         title.push_str(" - Rust");
 132         let tyname = it.type_();
 133         let desc = it.doc_value().as_ref().map(|doc| plain_text_summary(&doc));
 134         let desc = if let Some(desc) = desc {
 135             desc
 136         } else if it.is_crate() {
 137             format!("API documentation for the Rust `{}` crate.", self.shared.layout.krate)
 138         } else {
 139             format!(
 140                 "API documentation for the Rust `{}` {} in crate `{}`.",
 141                 it.name.as_ref().unwrap(),
 142                 tyname,
 143                 self.shared.layout.krate
 144             )
 145         };
 146         let keywords = make_item_keywords(it);
 147         let page = layout::Page {
 148             css_class: tyname.as_str(),
 149             root_path: &self.root_path(),
 150             static_root_path: self.shared.static_root_path.as_deref(),
 151             title: &title,
 152             description: &desc,
 153             keywords: &keywords,
 154             resource_suffix: &self.shared.resource_suffix,
 155             extra_scripts: &[],
 156             static_extra_scripts: &[],
 157         };
 158
 159         if !self.render_redirect_pages {
 160             layout::render(
 161                 &self.shared.layout,
 162                 &page,
 163                 |buf: &mut _| print_sidebar(self, it, buf),
 164                 |buf: &mut _| print_item(self, it, buf),
 165                 &self.shared.style_files,
 166             )
 167         } else {
 168             if let Some(&(ref names, ty)) = self.cache.paths.get(&it.def_id) {
 169                 let mut path = String::new();
 170                 for name in &names[..names.len() - 1] {
 171                     path.push_str(name);
 172                     path.push('/');
 173                 }
 174                 path.push_str(&item_path(ty, names.last().unwrap()));
 175                 match self.shared.redirections {
 176                     Some(ref redirections) => {
 177                         let mut current_path = String::new();
 178                         for name in &self.current {
 179                             current_path.push_str(name);
 180                             current_path.push('/');
 181                         }
 182                         current_path.push_str(&item_path(ty, names.last().unwrap()));
 183                         redirections.borrow_mut().insert(current_path, path);
 184                     }
 185                     None => return layout::redirect(&format!("{}{}", self.root_path(), path)),
 186                 }
 187             }
 188             String::new()
 189         }
 190     }
 191
 192     /// Construct a map of items shown in the sidebar to a plain-text summary of their docs.
 193     fn build_sidebar_items(&self, m: &clean::Module) -> BTreeMap<String, Vec<NameDoc>> {
 194         // BTreeMap instead of HashMap to get a sorted output
 195         let mut map: BTreeMap<_, Vec<_>> = BTreeMap::new();
 196         for item in &m.items {
 197             if item.is_stripped() {
 198                 continue;
 199             }
 200
 201             let short = item.type_();
 202             let myname = match item.name {
 203                 None => continue,
 204                 Some(ref s) => s.to_string(),
 205             };
 206             let short = short.to_string();
 207             map.entry(short).or_default().push((
 208                 myname,
 209                 Some(item.doc_value().map_or_else(String::new, |s| plain_text_summary(&s))),
 210             ));
 211         }
 212
 213         if self.shared.sort_modules_alphabetically {
 214             for items in map.values_mut() {
 215                 items.sort();
 216             }
 217         }
 218         map
 219     }
 220
 221     /// Generates a url appropriate for an `href` attribute back to the source of
 222     /// this item.
 223     ///
 224     /// The url generated, when clicked, will redirect the browser back to the
 225     /// original source code.
 226     ///
 227     /// If `None` is returned, then a source link couldn't be generated. This
 228     /// may happen, for example, with externally inlined items where the source
 229     /// of their crate documentation isn't known.
 230     pub(super) fn src_href(&self, item: &clean::Item) -> Option<String> {
 231         if item.source.is_dummy() {
 232             return None;
 233         }
 234         let mut root = self.root_path();
 235         let mut path = String::new();
 236         let cnum = item.source.cnum(self.sess());
 237
 238         // We can safely ignore synthetic `SourceFile`s.
 239         let file = match item.source.filename(self.sess()) {
 240             FileName::Real(ref path) => path.local_path().to_path_buf(),
 241             _ => return None,
 242         };
 243         let file = &file;
 244
 245         let symbol;
 246         let (krate, path) = if cnum == LOCAL_CRATE {
 247             if let Some(path) = self.shared.local_sources.get(file) {
 248                 (self.shared.layout.krate.as_str(), path)
 249             } else {
 250                 return None;
 251             }
 252         } else {
 253             let (krate, src_root) = match *self.cache.extern_locations.get(&cnum)? {
 254                 (name, ref src, ExternalLocation::Local) => (name, src),
 255                 (name, ref src, ExternalLocation::Remote(ref s)) => {
 256                     root = s.to_string();
 257                     (name, src)
 258                 }
 259                 (_, _, ExternalLocation::Unknown) => return None,
 260             };
 261
 262             sources::clean_path(&src_root, file, false, |component| {
 263                 path.push_str(&component.to_string_lossy());
 264                 path.push('/');
 265             });
 266             let mut fname = file.file_name().expect("source has no filename").to_os_string();
 267             fname.push(".html");
 268             path.push_str(&fname.to_string_lossy());
 269             symbol = krate.as_str();
 270             (&*symbol, &path)
 271         };
 272
 273         let loline = item.source.lo(self.sess()).line;
 274         let hiline = item.source.hi(self.sess()).line;
 275         let lines =
 276             if loline == hiline { loline.to_string() } else { format!("{}-{}", loline, hiline) };
 277         Some(format!(
 278             "{root}src/{krate}/{path}#{lines}",
 279             root = Escape(&root),
 280             krate = krate,
 281             path = path,
 282             lines = lines
 283         ))
 284     }
 285 }
 286
 287 /// Generates the documentation for `crate` into the directory `dst`
 288 impl<'tcx> FormatRenderer<'tcx> for Context<'tcx> {
 289     fn descr() -> &'static str {
 290         "html"
 291     }
 292
 293     fn init(
 294         mut krate: clean::Crate,
 295         options: RenderOptions,
 296         edition: Edition,
 297         mut cache: Cache,
 298         tcx: TyCtxt<'tcx>,
 299     ) -> Result<(Self, clean::Crate), Error> {
 300         // need to save a copy of the options for rendering the index page
 301         let md_opts = options.clone();
 302         let RenderOptions {
 303             output,
 304             external_html,
 305             id_map,
 306             playground_url,
 307             sort_modules_alphabetically,
 308             themes: style_files,
 309             default_settings,
 310             extension_css,
 311             resource_suffix,
 312             static_root_path,
 313             generate_search_filter,
 314             unstable_features,
 315             generate_redirect_map,
 316             ..
 317         } = options;
 318
 319         let src_root = match krate.src {
 320             FileName::Real(ref p) => match p.local_path().parent() {
 321                 Some(p) => p.to_path_buf(),
 322                 None => PathBuf::new(),
 323             },
 324             _ => PathBuf::new(),
 325         };
 326         // If user passed in `--playground-url` arg, we fill in crate name here
 327         let mut playground = None;
 328         if let Some(url) = playground_url {
 329             playground =
 330                 Some(markdown::Playground { crate_name: Some(krate.name.to_string()), url });
 331         }
 332         let mut layout = layout::Layout {
 333             logo: String::new(),
 334             favicon: String::new(),
 335             external_html,
 336             default_settings,
 337             krate: krate.name.to_string(),
 338             css_file_extension: extension_css,
 339             generate_search_filter,
 340         };
 341         let mut issue_tracker_base_url = None;
 342         let mut include_sources = true;
 343
 344         // Crawl the crate attributes looking for attributes which control how we're
 345         // going to emit HTML
 346         if let Some(attrs) = krate.module.as_ref().map(|m| &m.attrs) {
 347             for attr in attrs.lists(sym::doc) {
 348                 match (attr.name_or_empty(), attr.value_str()) {
 349                     (sym::html_favicon_url, Some(s)) => {
 350                         layout.favicon = s.to_string();
 351                     }
 352                     (sym::html_logo_url, Some(s)) => {
 353                         layout.logo = s.to_string();
 354                     }
 355                     (sym::html_playground_url, Some(s)) => {
 356                         playground = Some(markdown::Playground {
 357                             crate_name: Some(krate.name.to_string()),
 358                             url: s.to_string(),
 359                         });
 360                     }
 361                     (sym::issue_tracker_base_url, Some(s)) => {
 362                         issue_tracker_base_url = Some(s.to_string());
 363                     }
 364                     (sym::html_no_source, None) if attr.is_word() => {
 365                         include_sources = false;
 366                     }
 367                     _ => {}
 368                 }
 369             }
 370         }
 371         let (sender, receiver) = channel();
 372         let mut scx = SharedContext {
 373             tcx,
 374             collapsed: krate.collapsed,
 375             src_root,
 376             include_sources,
 377             local_sources: Default::default(),
 378             issue_tracker_base_url,
 379             layout,
 380             created_dirs: Default::default(),
 381             sort_modules_alphabetically,
 382             style_files,
 383             resource_suffix,
 384             static_root_path,
 385             fs: DocFS::new(sender),
 386             edition,
 387             codes: ErrorCodes::from(unstable_features.is_nightly_build()),
 388             playground,
 389             all: RefCell::new(AllTypes::new()),
 390             errors: receiver,
 391             redirections: if generate_redirect_map { Some(Default::default()) } else { None },
 392         };
 393
 394         // Add the default themes to the `Vec` of stylepaths
 395         //
 396         // Note that these must be added before `sources::render` is called
 397         // so that the resulting source pages are styled
 398         //
 399         // `light.css` is not disabled because it is the stylesheet that stays loaded
 400         // by the browser as the theme stylesheet. The theme system (hackily) works by
 401         // changing the href to this stylesheet. All other themes are disabled to
 402         // prevent rule conflicts
 403         scx.style_files.push(StylePath { path: PathBuf::from("light.css"), disabled: false });
 404         scx.style_files.push(StylePath { path: PathBuf::from("dark.css"), disabled: true });
 405         scx.style_files.push(StylePath { path: PathBuf::from("ayu.css"), disabled: true });
 406
 407         let dst = output;
 408         scx.ensure_dir(&dst)?;
 409         krate = sources::render(&dst, &mut scx, krate)?;
 410
 411         // Build our search index
 412         let index = build_index(&krate, &mut cache, tcx);
 413
 414         let mut cx = Context {
 415             current: Vec::new(),
 416             dst,
 417             render_redirect_pages: false,
 418             id_map: RefCell::new(id_map),
 419             deref_id_map: RefCell::new(FxHashMap::default()),
 420             shared: Rc::new(scx),
 421             cache: Rc::new(cache),
 422         };
 423
 424         CURRENT_DEPTH.with(|s| s.set(0));
 425
 426         // Write shared runs within a flock; disable thread dispatching of IO temporarily.
 427         Rc::get_mut(&mut cx.shared).unwrap().fs.set_sync_only(true);
 428         write_shared(&cx, &krate, index, &md_opts)?;
 429         Rc::get_mut(&mut cx.shared).unwrap().fs.set_sync_only(false);
 430         Ok((cx, krate))
 431     }
 432
 433     fn make_child_renderer(&self) -> Self {
 434         let mut id_map = IdMap::new();
 435         id_map.populate(&INITIAL_IDS);
 436
 437         Self {
 438             current: self.current.clone(),
 439             dst: self.dst.clone(),
 440             render_redirect_pages: self.render_redirect_pages,
 441             id_map: RefCell::new(id_map),
 442             deref_id_map: RefCell::new(FxHashMap::default()),
 443             shared: Rc::clone(&self.shared),
 444             cache: Rc::clone(&self.cache),
 445         }
 446     }
 447
 448     fn after_krate(
 449         &mut self,
 450         krate: &clean::Crate,
 451         diag: &rustc_errors::Handler,
 452     ) -> Result<(), Error> {
 453         let final_file = self.dst.join(&*krate.name.as_str()).join("all.html");
 454         let settings_file = self.dst.join("settings.html");
 455         let crate_name = krate.name;
 456
 457         let mut root_path = self.dst.to_str().expect("invalid path").to_owned();
 458         if !root_path.ends_with('/') {
 459             root_path.push('/');
 460         }
 461         let mut page = layout::Page {
 462             title: "List of all items in this crate",
 463             css_class: "mod",
 464             root_path: "../",
 465             static_root_path: self.shared.static_root_path.as_deref(),
 466             description: "List of all items in this crate",
 467             keywords: BASIC_KEYWORDS,
 468             resource_suffix: &self.shared.resource_suffix,
 469             extra_scripts: &[],
 470             static_extra_scripts: &[],
 471         };
 472         let sidebar = if let Some(ref version) = self.cache.crate_version {
 473             format!(
 474                 "<p class=\"location\">Crate {}</p>\
 475                      <div class=\"block version\">\
 476                          <p>Version {}</p>\
 477                      </div>\
 478                      <a id=\"all-types\" href=\"index.html\"><p>Back to index</p></a>",
 479                 crate_name,
 480                 Escape(version),
 481             )
 482         } else {
 483             String::new()
 484         };
 485         let all = self.shared.all.replace(AllTypes::new());
 486         let v = layout::render(
 487             &self.shared.layout,
 488             &page,
 489             sidebar,
 490             |buf: &mut Buffer| all.print(buf),
 491             &self.shared.style_files,
 492         );
 493         self.shared.fs.write(&final_file, v.as_bytes())?;
 494
 495         // Generating settings page.
 496         page.title = "Rustdoc settings";
 497         page.description = "Settings of Rustdoc";
 498         page.root_path = "./";
 499
 500         let mut style_files = self.shared.style_files.clone();
 501         let sidebar = "<p class=\"location\">Settings</p><div class=\"sidebar-elems\"></div>";
 502         style_files.push(StylePath { path: PathBuf::from("settings.css"), disabled: false });
 503         let v = layout::render(
 504             &self.shared.layout,
 505             &page,
 506             sidebar,
 507             settings(
 508                 self.shared.static_root_path.as_deref().unwrap_or("./"),
 509                 &self.shared.resource_suffix,
 510                 &self.shared.style_files,
 511             )?,
 512             &style_files,
 513         );
 514         self.shared.fs.write(&settings_file, v.as_bytes())?;
 515         if let Some(ref redirections) = self.shared.redirections {
 516             if !redirections.borrow().is_empty() {
 517                 let redirect_map_path =
 518                     self.dst.join(&*krate.name.as_str()).join("redirect-map.json");
 519                 let paths = serde_json::to_string(&*redirections.borrow()).unwrap();
 520                 self.shared.ensure_dir(&self.dst.join(&*krate.name.as_str()))?;
 521                 self.shared.fs.write(&redirect_map_path, paths.as_bytes())?;
 522             }
 523         }
 524
 525         // Flush pending errors.
 526         Rc::get_mut(&mut self.shared).unwrap().fs.close();
 527         let nb_errors = self.shared.errors.iter().map(|err| diag.struct_err(&err).emit()).count();
 528         if nb_errors > 0 {
 529             Err(Error::new(io::Error::new(io::ErrorKind::Other, "I/O error"), ""))
 530         } else {
 531             Ok(())
 532         }
 533     }
 534
 535     fn mod_item_in(&mut self, item: &clean::Item, item_name: &str) -> Result<(), Error> {
 536         // Stripped modules survive the rustdoc passes (i.e., `strip-private`)
 537         // if they contain impls for public types. These modules can also
 538         // contain items such as publicly re-exported structures.
 539         //
 540         // External crates will provide links to these structures, so
 541         // these modules are recursed into, but not rendered normally
 542         // (a flag on the context).
 543         if !self.render_redirect_pages {
 544             self.render_redirect_pages = item.is_stripped();
 545         }
 546         let scx = &self.shared;
 547         self.dst.push(item_name);
 548         self.current.push(item_name.to_owned());
 549
 550         info!("Recursing into {}", self.dst.display());
 551
 552         let buf = self.render_item(item, false);
 553         // buf will be empty if the module is stripped and there is no redirect for it
 554         if !buf.is_empty() {
 555             self.shared.ensure_dir(&self.dst)?;
 556             let joint_dst = self.dst.join("index.html");
 557             scx.fs.write(&joint_dst, buf.as_bytes())?;
 558         }
 559
 560         // Render sidebar-items.js used throughout this module.
 561         if !self.render_redirect_pages {
 562             let module = match *item.kind {
 563                 clean::StrippedItem(box clean::ModuleItem(ref m)) | clean::ModuleItem(ref m) => m,
 564                 _ => unreachable!(),
 565             };
 566             let items = self.build_sidebar_items(module);
 567             let js_dst = self.dst.join("sidebar-items.js");
 568             let v = format!("initSidebarItems({});", serde_json::to_string(&items).unwrap());
 569             scx.fs.write(&js_dst, &v)?;
 570         }
 571         Ok(())
 572     }
 573
 574     fn mod_item_out(&mut self, _item_name: &str) -> Result<(), Error> {
 575         info!("Recursed; leaving {}", self.dst.display());
 576
 577         // Go back to where we were at
 578         self.dst.pop();
 579         self.current.pop();
 580         Ok(())
 581     }
 582
 583     fn item(&mut self, item: clean::Item) -> Result<(), Error> {
 584         // Stripped modules survive the rustdoc passes (i.e., `strip-private`)
 585         // if they contain impls for public types. These modules can also
 586         // contain items such as publicly re-exported structures.
 587         //
 588         // External crates will provide links to these structures, so
 589         // these modules are recursed into, but not rendered normally
 590         // (a flag on the context).
 591         if !self.render_redirect_pages {
 592             self.render_redirect_pages = item.is_stripped();
 593         }
 594
 595         let buf = self.render_item(&item, true);
 596         // buf will be empty if the item is stripped and there is no redirect for it
 597         if !buf.is_empty() {
 598             let name = item.name.as_ref().unwrap();
 599             let item_type = item.type_();
 600             let file_name = &item_path(item_type, &name.as_str());
 601             self.shared.ensure_dir(&self.dst)?;
 602             let joint_dst = self.dst.join(file_name);
 603             self.shared.fs.write(&joint_dst, buf.as_bytes())?;
 604
 605             if !self.render_redirect_pages {
 606                 self.shared.all.borrow_mut().append(full_path(self, &item), &item_type);
 607             }
 608             // If the item is a macro, redirect from the old macro URL (with !)
 609             // to the new one (without).
 610             if item_type == ItemType::Macro {
 611                 let redir_name = format!("{}.{}!.html", item_type, name);
 612                 if let Some(ref redirections) = self.shared.redirections {
 613                     let crate_name = &self.shared.layout.krate;
 614                     redirections.borrow_mut().insert(
 615                         format!("{}/{}", crate_name, redir_name),
 616                         format!("{}/{}", crate_name, file_name),
 617                     );
 618                 } else {
 619                     let v = layout::redirect(file_name);
 620                     let redir_dst = self.dst.join(redir_name);
 621                     self.shared.fs.write(&redir_dst, v.as_bytes())?;
 622                 }
 623             }
 624         }
 625         Ok(())
 626     }
 627
 628     fn cache(&self) -> &Cache {
 629         &self.cache
 630     }
 631 }
 632
 633 fn make_item_keywords(it: &clean::Item) -> String {
 634     format!("{}, {}", BASIC_KEYWORDS, it.name.as_ref().unwrap())
 635 }