src/librustdoc/html/render/context.rs

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