src/librustdoc/html/render/context.rs

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