src/librustdoc/html/render.rs

   1 // Copyright 2013-2014 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 //! Rustdoc's HTML Rendering module
  12 //!
  13 //! This modules contains the bulk of the logic necessary for rendering a
  14 //! rustdoc `clean::Crate` instance to a set of static HTML pages. This
  15 //! rendering process is largely driven by the `format!` syntax extension to
  16 //! perform all I/O into files and streams.
  17 //!
  18 //! The rendering process is largely driven by the `Context` and `Cache`
  19 //! structures. The cache is pre-populated by crawling the crate in question,
  20 //! and then it is shared among the various rendering tasks. The cache is meant
  21 //! to be a fairly large structure not implementing `Clone` (because it's shared
  22 //! among tasks). The context, however, should be a lightweight structure. This
  23 //! is cloned per-task and contains information about what is currently being
  24 //! rendered.
  25 //!
  26 //! In order to speed up rendering (mostly because of markdown rendering), the
  27 //! rendering process has been parallelized. This parallelization is only
  28 //! exposed through the `crate` method on the context, and then also from the
  29 //! fact that the shared cache is stored in TLS (and must be accessed as such).
  30 //!
  31 //! In addition to rendering the crate itself, this module is also responsible
  32 //! for creating the corresponding search index and source file renderings.
  33 //! These tasks are not parallelized (they haven't been a bottleneck yet), and
  34 //! both occur before the crate is rendered.
  35
  36 use collections::{HashMap, HashSet};
  37 use std::fmt;
  38 use std::io::{fs, File, BufferedWriter, MemWriter, BufferedReader};
  39 use std::io;
  40 use std::str;
  41 use std::string::String;
  42
  43 use sync::Arc;
  44 use serialize::json::ToJson;
  45 use syntax::ast;
  46 use syntax::ast_util;
  47 use syntax::attr;
  48 use syntax::parse::token::InternedString;
  49 use rustc::util::nodemap::NodeSet;
  50
  51 use clean;
  52 use doctree;
  53 use fold::DocFolder;
  54 use html::format::{VisSpace, Method, FnStyleSpace};
  55 use html::highlight;
  56 use html::item_type::{ItemType, shortty};
  57 use html::item_type;
  58 use html::layout;
  59 use html::markdown::Markdown;
  60 use html::markdown;
  61
  62 /// Major driving force in all rustdoc rendering. This contains information
  63 /// about where in the tree-like hierarchy rendering is occurring and controls
  64 /// how the current page is being rendered.
  65 ///
  66 /// It is intended that this context is a lightweight object which can be fairly
  67 /// easily cloned because it is cloned per work-job (about once per item in the
  68 /// rustdoc tree).
  69 #[deriving(Clone)]
  70 pub struct Context {
  71     /// Current hierarchy of components leading down to what's currently being
  72     /// rendered
  73     pub current: Vec<String> ,
  74     /// String representation of how to get back to the root path of the 'doc/'
  75     /// folder in terms of a relative URL.
  76     pub root_path: String,
  77     /// The current destination folder of where HTML artifacts should be placed.
  78     /// This changes as the context descends into the module hierarchy.
  79     pub dst: Path,
  80     /// This describes the layout of each page, and is not modified after
  81     /// creation of the context (contains info like the favicon)
  82     pub layout: layout::Layout,
  83     /// This map is a list of what should be displayed on the sidebar of the
  84     /// current page. The key is the section header (traits, modules,
  85     /// functions), and the value is the list of containers belonging to this
  86     /// header. This map will change depending on the surrounding context of the
  87     /// page.
  88     pub sidebar: HashMap<String, Vec<String>>,
  89     /// This flag indicates whether [src] links should be generated or not. If
  90     /// the source files are present in the html rendering, then this will be
  91     /// `true`.
  92     pub include_sources: bool,
  93 }
  94
  95 /// Indicates where an external crate can be found.
  96 pub enum ExternalLocation {
  97     /// Remote URL root of the external crate
  98     Remote(String),
  99     /// This external crate can be found in the local doc/ folder
 100     Local,
 101     /// The external crate could not be found.
 102     Unknown,
 103 }
 104
 105 /// Different ways an implementor of a trait can be rendered.
 106 pub enum Implementor {
 107     /// Paths are displayed specially by omitting the `impl XX for` cruft
 108     PathType(clean::Type),
 109     /// This is the generic representation of a trait implementor, used for
 110     /// primitive types and otherwise non-path types.
 111     OtherType(clean::Generics, /* trait */ clean::Type, /* for */ clean::Type),
 112 }
 113
 114 /// This cache is used to store information about the `clean::Crate` being
 115 /// rendered in order to provide more useful documentation. This contains
 116 /// information like all implementors of a trait, all traits a type implements,
 117 /// documentation for all known traits, etc.
 118 ///
 119 /// This structure purposefully does not implement `Clone` because it's intended
 120 /// to be a fairly large and expensive structure to clone. Instead this adheres
 121 /// to `Send` so it may be stored in a `Arc` instance and shared among the various
 122 /// rendering tasks.
 123 pub struct Cache {
 124     /// Mapping of typaram ids to the name of the type parameter. This is used
 125     /// when pretty-printing a type (so pretty printing doesn't have to
 126     /// painfully maintain a context like this)
 127     pub typarams: HashMap<ast::DefId, String>,
 128
 129     /// Maps a type id to all known implementations for that type. This is only
 130     /// recognized for intra-crate `ResolvedPath` types, and is used to print
 131     /// out extra documentation on the page of an enum/struct.
 132     ///
 133     /// The values of the map are a list of implementations and documentation
 134     /// found on that implementation.
 135     pub impls: HashMap<ast::DefId, Vec<(clean::Impl, Option<String>)>>,
 136
 137     /// Maintains a mapping of local crate node ids to the fully qualified name
 138     /// and "short type description" of that node. This is used when generating
 139     /// URLs when a type is being linked to. External paths are not located in
 140     /// this map because the `External` type itself has all the information
 141     /// necessary.
 142     pub paths: HashMap<ast::DefId, (Vec<String>, ItemType)>,
 143
 144     /// This map contains information about all known traits of this crate.
 145     /// Implementations of a crate should inherit the documentation of the
 146     /// parent trait if no extra documentation is specified, and default methods
 147     /// should show up in documentation about trait implementations.
 148     pub traits: HashMap<ast::DefId, clean::Trait>,
 149
 150     /// When rendering traits, it's often useful to be able to list all
 151     /// implementors of the trait, and this mapping is exactly, that: a mapping
 152     /// of trait ids to the list of known implementors of the trait
 153     pub implementors: HashMap<ast::DefId, Vec<Implementor>>,
 154
 155     /// Cache of where external crate documentation can be found.
 156     pub extern_locations: HashMap<ast::CrateNum, ExternalLocation>,
 157
 158     // Private fields only used when initially crawling a crate to build a cache
 159
 160     stack: Vec<String>,
 161     parent_stack: Vec<ast::DefId>,
 162     search_index: Vec<IndexItem>,
 163     privmod: bool,
 164     public_items: NodeSet,
 165
 166     // In rare case where a structure is defined in one module but implemented
 167     // in another, if the implementing module is parsed before defining module,
 168     // then the fully qualified name of the structure isn't presented in `paths`
 169     // yet when its implementation methods are being indexed. Caches such methods
 170     // and their parent id here and indexes them at the end of crate parsing.
 171     orphan_methods: Vec<(ast::NodeId, clean::Item)>,
 172 }
 173
 174 /// Helper struct to render all source code to HTML pages
 175 struct SourceCollector<'a> {
 176     cx: &'a mut Context,
 177
 178     /// Processed source-file paths
 179     seen: HashSet<String>,
 180     /// Root destination to place all HTML output into
 181     dst: Path,
 182 }
 183
 184 /// Wrapper struct to render the source code of a file. This will do things like
 185 /// adding line numbers to the left-hand side.
 186 struct Source<'a>(&'a str);
 187
 188 // Helper structs for rendering items/sidebars and carrying along contextual
 189 // information
 190
 191 struct Item<'a> { cx: &'a Context, item: &'a clean::Item, }
 192 struct Sidebar<'a> { cx: &'a Context, item: &'a clean::Item, }
 193
 194 /// Struct representing one entry in the JS search index. These are all emitted
 195 /// by hand to a large JS file at the end of cache-creation.
 196 struct IndexItem {
 197     ty: ItemType,
 198     name: String,
 199     path: String,
 200     desc: String,
 201     parent: Option<ast::DefId>,
 202 }
 203
 204 // TLS keys used to carry information around during rendering.
 205
 206 local_data_key!(pub cache_key: Arc<Cache>)
 207 local_data_key!(pub current_location_key: Vec<String> )
 208
 209 /// Generates the documentation for `crate` into the directory `dst`
 210 pub fn run(mut krate: clean::Crate, dst: Path) -> io::IoResult<()> {
 211     let mut cx = Context {
 212         dst: dst,
 213         current: Vec::new(),
 214         root_path: String::new(),
 215         sidebar: HashMap::new(),
 216         layout: layout::Layout {
 217             logo: "".to_strbuf(),
 218             favicon: "".to_strbuf(),
 219             krate: krate.name.clone(),
 220         },
 221         include_sources: true,
 222     };
 223     try!(mkdir(&cx.dst));
 224
 225     match krate.module.as_ref().map(|m| m.doc_list().unwrap_or(&[])) {
 226         Some(attrs) => {
 227             for attr in attrs.iter() {
 228                 match *attr {
 229                     clean::NameValue(ref x, ref s)
 230                             if "html_favicon_url" == x.as_slice() => {
 231                         cx.layout.favicon = s.to_strbuf();
 232                     }
 233                     clean::NameValue(ref x, ref s)
 234                             if "html_logo_url" == x.as_slice() => {
 235                         cx.layout.logo = s.to_strbuf();
 236                     }
 237                     clean::Word(ref x)
 238                             if "html_no_source" == x.as_slice() => {
 239                         cx.include_sources = false;
 240                     }
 241                     _ => {}
 242                 }
 243             }
 244         }
 245         None => {}
 246     }
 247
 248     // Crawl the crate to build various caches used for the output
 249     let analysis = ::analysiskey.get();
 250     let public_items = analysis.as_ref().map(|a| a.public_items.clone());
 251     let public_items = public_items.unwrap_or(NodeSet::new());
 252     let paths = analysis.as_ref().map(|a| {
 253         let paths = a.external_paths.borrow_mut().take_unwrap();
 254         paths.move_iter().map(|(k, (v, t))| {
 255             (k, (v, match t {
 256                 clean::TypeStruct => item_type::Struct,
 257                 clean::TypeEnum => item_type::Enum,
 258                 clean::TypeFunction => item_type::Function,
 259                 clean::TypeTrait => item_type::Trait,
 260                 clean::TypeModule => item_type::Module,
 261                 clean::TypeStatic => item_type::Static,
 262                 clean::TypeVariant => item_type::Variant,
 263             }))
 264         }).collect()
 265     }).unwrap_or(HashMap::new());
 266     let mut cache = Cache {
 267         impls: HashMap::new(),
 268         paths: paths,
 269         implementors: HashMap::new(),
 270         stack: Vec::new(),
 271         parent_stack: Vec::new(),
 272         search_index: Vec::new(),
 273         extern_locations: HashMap::new(),
 274         privmod: false,
 275         public_items: public_items,
 276         orphan_methods: Vec::new(),
 277         traits: analysis.as_ref().map(|a| {
 278             a.external_traits.borrow_mut().take_unwrap()
 279         }).unwrap_or(HashMap::new()),
 280         typarams: analysis.as_ref().map(|a| {
 281             a.external_typarams.borrow_mut().take_unwrap()
 282         }).unwrap_or(HashMap::new()),
 283     };
 284     cache.stack.push(krate.name.clone());
 285     krate = cache.fold_crate(krate);
 286
 287     let mut nodeid_to_pathid = HashMap::new();
 288     let mut pathid_to_nodeid = Vec::new();
 289     {
 290         let Cache { search_index: ref mut index,
 291                     orphan_methods: ref meths, paths: ref mut paths, ..} = cache;
 292
 293         // Attach all orphan methods to the type's definition if the type
 294         // has since been learned.
 295         for &(pid, ref item) in meths.iter() {
 296             let did = ast_util::local_def(pid);
 297             match paths.find(&did) {
 298                 Some(&(ref fqp, _)) => {
 299                     index.push(IndexItem {
 300                         ty: shortty(item),
 301                         name: item.name.clone().unwrap(),
 302                         path: fqp.slice_to(fqp.len() - 1).connect("::")
 303                                                          .to_strbuf(),
 304                         desc: shorter(item.doc_value()).to_strbuf(),
 305                         parent: Some(did),
 306                     });
 307                 },
 308                 None => {}
 309             }
 310         };
 311
 312         // Reduce `NodeId` in paths into smaller sequential numbers,
 313         // and prune the paths that do not appear in the index.
 314         for item in index.iter() {
 315             match item.parent {
 316                 Some(nodeid) => {
 317                     if !nodeid_to_pathid.contains_key(&nodeid) {
 318                         let pathid = pathid_to_nodeid.len();
 319                         nodeid_to_pathid.insert(nodeid, pathid);
 320                         pathid_to_nodeid.push(nodeid);
 321                     }
 322                 }
 323                 None => {}
 324             }
 325         }
 326         assert_eq!(nodeid_to_pathid.len(), pathid_to_nodeid.len());
 327     }
 328
 329     // Publish the search index
 330     let index = {
 331         let mut w = MemWriter::new();
 332         try!(write!(&mut w, r#"searchIndex['{}'] = \{"items":["#, krate.name));
 333
 334         let mut lastpath = "".to_strbuf();
 335         for (i, item) in cache.search_index.iter().enumerate() {
 336             // Omit the path if it is same to that of the prior item.
 337             let path;
 338             if lastpath.as_slice() == item.path.as_slice() {
 339                 path = "";
 340             } else {
 341                 lastpath = item.path.to_strbuf();
 342                 path = item.path.as_slice();
 343             };
 344
 345             if i > 0 {
 346                 try!(write!(&mut w, ","));
 347             }
 348             try!(write!(&mut w, r#"[{:u},"{}","{}",{}"#,
 349                         item.ty, item.name, path,
 350                         item.desc.to_json().to_str()));
 351             match item.parent {
 352                 Some(nodeid) => {
 353                     let pathid = *nodeid_to_pathid.find(&nodeid).unwrap();
 354                     try!(write!(&mut w, ",{}", pathid));
 355                 }
 356                 None => {}
 357             }
 358             try!(write!(&mut w, "]"));
 359         }
 360
 361         try!(write!(&mut w, r#"],"paths":["#));
 362
 363         for (i, &did) in pathid_to_nodeid.iter().enumerate() {
 364             let &(ref fqp, short) = cache.paths.find(&did).unwrap();
 365             if i > 0 {
 366                 try!(write!(&mut w, ","));
 367             }
 368             try!(write!(&mut w, r#"[{:u},"{}"]"#,
 369                         short, *fqp.last().unwrap()));
 370         }
 371
 372         try!(write!(&mut w, r"]\};"));
 373
 374         str::from_utf8(w.unwrap().as_slice()).unwrap().to_owned()
 375     };
 376
 377     // Write out the shared files. Note that these are shared among all rustdoc
 378     // docs placed in the output directory, so this needs to be a synchronized
 379     // operation with respect to all other rustdocs running around.
 380     {
 381         try!(mkdir(&cx.dst));
 382         let _lock = ::flock::Lock::new(&cx.dst.join(".lock"));
 383
 384         // Add all the static files. These may already exist, but we just
 385         // overwrite them anyway to make sure that they're fresh and up-to-date.
 386         try!(write(cx.dst.join("jquery.js"),
 387                    include_bin!("static/jquery-2.1.0.min.js")));
 388         try!(write(cx.dst.join("main.js"), include_bin!("static/main.js")));
 389         try!(write(cx.dst.join("main.css"), include_bin!("static/main.css")));
 390         try!(write(cx.dst.join("normalize.css"),
 391                    include_bin!("static/normalize.css")));
 392         try!(write(cx.dst.join("FiraSans-Regular.woff"),
 393                    include_bin!("static/FiraSans-Regular.woff")));
 394         try!(write(cx.dst.join("FiraSans-Medium.woff"),
 395                    include_bin!("static/FiraSans-Medium.woff")));
 396         try!(write(cx.dst.join("Heuristica-Regular.woff"),
 397                    include_bin!("static/Heuristica-Regular.woff")));
 398         try!(write(cx.dst.join("Heuristica-Italic.woff"),
 399                    include_bin!("static/Heuristica-Italic.woff")));
 400         try!(write(cx.dst.join("Heuristica-Bold.woff"),
 401                    include_bin!("static/Heuristica-Bold.woff")));
 402
 403         fn collect(path: &Path, krate: &str,
 404                    key: &str) -> io::IoResult<Vec<String>> {
 405             let mut ret = Vec::new();
 406             if path.exists() {
 407                 for line in BufferedReader::new(File::open(path)).lines() {
 408                     let line = try!(line);
 409                     if !line.as_slice().starts_with(key) {
 410                         continue
 411                     }
 412                     if line.as_slice().starts_with(
 413                             format!("{}['{}']", key, krate).as_slice()) {
 414                         continue
 415                     }
 416                     ret.push(line.to_strbuf());
 417                 }
 418             }
 419             return Ok(ret);
 420         }
 421
 422         // Update the search index
 423         let dst = cx.dst.join("search-index.js");
 424         let all_indexes = try!(collect(&dst, krate.name.as_slice(),
 425                                        "searchIndex"));
 426         let mut w = try!(File::create(&dst));
 427         try!(writeln!(&mut w, r"var searchIndex = \{\};"));
 428         try!(writeln!(&mut w, "{}", index));
 429         for index in all_indexes.iter() {
 430             try!(writeln!(&mut w, "{}", *index));
 431         }
 432         try!(writeln!(&mut w, "initSearch(searchIndex);"));
 433
 434         // Update the list of all implementors for traits
 435         let dst = cx.dst.join("implementors");
 436         try!(mkdir(&dst));
 437         for (&did, imps) in cache.implementors.iter() {
 438             if ast_util::is_local(did) { continue }
 439             let &(ref remote_path, remote_item_type) = cache.paths.get(&did);
 440
 441             let mut mydst = dst.clone();
 442             for part in remote_path.slice_to(remote_path.len() - 1).iter() {
 443                 mydst.push(part.as_slice());
 444                 try!(mkdir(&mydst));
 445             }
 446             mydst.push(format!("{}.{}.js",
 447                                remote_item_type.to_static_str(),
 448                                *remote_path.get(remote_path.len() - 1)));
 449             let all_implementors = try!(collect(&mydst, krate.name.as_slice(),
 450                                                 "implementors"));
 451
 452             try!(mkdir(&mydst.dir_path()));
 453             let mut f = BufferedWriter::new(try!(File::create(&mydst)));
 454             try!(writeln!(&mut f, r"(function() \{var implementors = \{\};"));
 455
 456             for implementor in all_implementors.iter() {
 457                 try!(writeln!(&mut f, "{}", *implementor));
 458             }
 459
 460             try!(write!(&mut f, r"implementors['{}'] = \{", krate.name));
 461             for imp in imps.iter() {
 462                 let &(ref path, item_type) = match *imp {
 463                     PathType(clean::ResolvedPath { did, .. }) => {
 464                         cache.paths.get(&did)
 465                     }
 466                     PathType(..) | OtherType(..) => continue,
 467                 };
 468                 try!(write!(&mut f, r#"{}:"#, *path.get(path.len() - 1)));
 469                 try!(write!(&mut f, r#""{}"#,
 470                             path.slice_to(path.len() - 1).connect("/")));
 471                 try!(write!(&mut f, r#"/{}.{}.html","#,
 472                             item_type.to_static_str(),
 473                             *path.get(path.len() - 1)));
 474             }
 475             try!(writeln!(&mut f, r"\};"));
 476             try!(writeln!(&mut f, "{}", r"
 477                 if (window.register_implementors) {
 478                     window.register_implementors(implementors);
 479                 } else {
 480                     window.pending_implementors = implementors;
 481                 }
 482             "));
 483             try!(writeln!(&mut f, r"\})()"));
 484         }
 485     }
 486
 487     // Render all source files (this may turn into a giant no-op)
 488     {
 489         info!("emitting source files");
 490         let dst = cx.dst.join("src");
 491         try!(mkdir(&dst));
 492         let dst = dst.join(krate.name.as_slice());
 493         try!(mkdir(&dst));
 494         let mut folder = SourceCollector {
 495             dst: dst,
 496             seen: HashSet::new(),
 497             cx: &mut cx,
 498         };
 499         krate = folder.fold_crate(krate);
 500     }
 501
 502     for &(n, ref e) in krate.externs.iter() {
 503         cache.extern_locations.insert(n, extern_location(e, &cx.dst));
 504         let did = ast::DefId { krate: n, node: ast::CRATE_NODE_ID };
 505         cache.paths.insert(did, (Vec::new(), item_type::Module));
 506     }
 507
 508     // And finally render the whole crate's documentation
 509     cx.krate(krate, cache)
 510 }
 511
 512 /// Writes the entire contents of a string to a destination, not attempting to
 513 /// catch any errors.
 514 fn write(dst: Path, contents: &[u8]) -> io::IoResult<()> {
 515     File::create(&dst).write(contents)
 516 }
 517
 518 /// Makes a directory on the filesystem, failing the task if an error occurs and
 519 /// skipping if the directory already exists.
 520 fn mkdir(path: &Path) -> io::IoResult<()> {
 521     if !path.exists() {
 522         fs::mkdir(path, io::UserRWX)
 523     } else {
 524         Ok(())
 525     }
 526 }
 527
 528 /// Takes a path to a source file and cleans the path to it. This canonicalizes
 529 /// things like ".." to components which preserve the "top down" hierarchy of a
 530 /// static HTML tree.
 531 // FIXME (#9639): The closure should deal with &[u8] instead of &str
 532 fn clean_srcpath(src: &[u8], f: |&str|) {
 533     let p = Path::new(src);
 534     if p.as_vec() != bytes!(".") {
 535         for c in p.str_components().map(|x|x.unwrap()) {
 536             if ".." == c {
 537                 f("up");
 538             } else {
 539                 f(c.as_slice())
 540             }
 541         }
 542     }
 543 }
 544
 545 /// Attempts to find where an external crate is located, given that we're
 546 /// rendering in to the specified source destination.
 547 fn extern_location(e: &clean::ExternalCrate, dst: &Path) -> ExternalLocation {
 548     // See if there's documentation generated into the local directory
 549     let local_location = dst.join(e.name.as_slice());
 550     if local_location.is_dir() {
 551         return Local;
 552     }
 553
 554     // Failing that, see if there's an attribute specifying where to find this
 555     // external crate
 556     for attr in e.attrs.iter() {
 557         match *attr {
 558             clean::List(ref x, ref list) if "doc" == x.as_slice() => {
 559                 for attr in list.iter() {
 560                     match *attr {
 561                         clean::NameValue(ref x, ref s)
 562                                 if "html_root_url" == x.as_slice() => {
 563                             if s.as_slice().ends_with("/") {
 564                                 return Remote(s.to_strbuf());
 565                             }
 566                             return Remote(format_strbuf!("{}/", s));
 567                         }
 568                         _ => {}
 569                     }
 570                 }
 571             }
 572             _ => {}
 573         }
 574     }
 575
 576     // Well, at least we tried.
 577     return Unknown;
 578 }
 579
 580 impl<'a> DocFolder for SourceCollector<'a> {
 581     fn fold_item(&mut self, item: clean::Item) -> Option<clean::Item> {
 582         // If we're including source files, and we haven't seen this file yet,
 583         // then we need to render it out to the filesystem
 584         if self.cx.include_sources && !self.seen.contains(&item.source.filename) {
 585
 586             // If it turns out that we couldn't read this file, then we probably
 587             // can't read any of the files (generating html output from json or
 588             // something like that), so just don't include sources for the
 589             // entire crate. The other option is maintaining this mapping on a
 590             // per-file basis, but that's probably not worth it...
 591             self.cx
 592                 .include_sources = match self.emit_source(item.source
 593                                                               .filename
 594                                                               .as_slice()) {
 595                 Ok(()) => true,
 596                 Err(e) => {
 597                     println!("warning: source code was requested to be rendered, \
 598                               but processing `{}` had an error: {}",
 599                              item.source.filename, e);
 600                     println!("         skipping rendering of source code");
 601                     false
 602                 }
 603             };
 604             self.seen.insert(item.source.filename.clone());
 605         }
 606
 607         self.fold_item_recur(item)
 608     }
 609 }
 610
 611 impl<'a> SourceCollector<'a> {
 612     /// Renders the given filename into its corresponding HTML source file.
 613     fn emit_source(&mut self, filename: &str) -> io::IoResult<()> {
 614         let p = Path::new(filename);
 615
 616         // If we couldn't open this file, then just returns because it
 617         // probably means that it's some standard library macro thing and we
 618         // can't have the source to it anyway.
 619         let contents = match File::open(&p).read_to_end() {
 620             Ok(r) => r,
 621             // macros from other libraries get special filenames which we can
 622             // safely ignore
 623             Err(..) if filename.starts_with("<") &&
 624                        filename.ends_with("macros>") => return Ok(()),
 625             Err(e) => return Err(e)
 626         };
 627         let contents = str::from_utf8(contents.as_slice()).unwrap();
 628
 629         // Remove the utf-8 BOM if any
 630         let contents = if contents.starts_with("\ufeff") {
 631             contents.as_slice().slice_from(3)
 632         } else {
 633             contents.as_slice()
 634         };
 635
 636         // Create the intermediate directories
 637         let mut cur = self.dst.clone();
 638         let mut root_path = String::from_str("../../");
 639         clean_srcpath(p.dirname(), |component| {
 640             cur.push(component);
 641             mkdir(&cur).unwrap();
 642             root_path.push_str("../");
 643         });
 644
 645         cur.push(Vec::from_slice(p.filename().expect("source has no filename"))
 646                  .append(bytes!(".html")));
 647         let mut w = BufferedWriter::new(try!(File::create(&cur)));
 648
 649         let title = format!("{} -- source", cur.filename_display());
 650         let page = layout::Page {
 651             title: title.as_slice(),
 652             ty: "source",
 653             root_path: root_path.as_slice(),
 654         };
 655         try!(layout::render(&mut w as &mut Writer, &self.cx.layout,
 656                             &page, &(""), &Source(contents)));
 657         try!(w.flush());
 658         return Ok(());
 659     }
 660 }
 661
 662 impl DocFolder for Cache {
 663     fn fold_item(&mut self, item: clean::Item) -> Option<clean::Item> {
 664         // If this is a private module, we don't want it in the search index.
 665         let orig_privmod = match item.inner {
 666             clean::ModuleItem(..) => {
 667                 let prev = self.privmod;
 668                 self.privmod = prev || item.visibility != Some(ast::Public);
 669                 prev
 670             }
 671             _ => self.privmod,
 672         };
 673
 674         // Register any generics to their corresponding string. This is used
 675         // when pretty-printing types
 676         match item.inner {
 677             clean::StructItem(ref s)          => self.generics(&s.generics),
 678             clean::EnumItem(ref e)            => self.generics(&e.generics),
 679             clean::FunctionItem(ref f)        => self.generics(&f.generics),
 680             clean::TypedefItem(ref t)         => self.generics(&t.generics),
 681             clean::TraitItem(ref t)           => self.generics(&t.generics),
 682             clean::ImplItem(ref i)            => self.generics(&i.generics),
 683             clean::TyMethodItem(ref i)        => self.generics(&i.generics),
 684             clean::MethodItem(ref i)          => self.generics(&i.generics),
 685             clean::ForeignFunctionItem(ref f) => self.generics(&f.generics),
 686             _ => {}
 687         }
 688
 689         // Propagate a trait methods' documentation to all implementors of the
 690         // trait
 691         match item.inner {
 692             clean::TraitItem(ref t) => {
 693                 self.traits.insert(item.def_id, t.clone());
 694             }
 695             _ => {}
 696         }
 697
 698         // Collect all the implementors of traits.
 699         match item.inner {
 700             clean::ImplItem(ref i) => {
 701                 match i.trait_ {
 702                     Some(clean::ResolvedPath{ did, .. }) => {
 703                         let v = self.implementors.find_or_insert_with(did, |_| {
 704                             Vec::new()
 705                         });
 706                         match i.for_ {
 707                             clean::ResolvedPath{..} => {
 708                                 v.unshift(PathType(i.for_.clone()));
 709                             }
 710                             _ => {
 711                                 v.push(OtherType(i.generics.clone(),
 712                                                  i.trait_.get_ref().clone(),
 713                                                  i.for_.clone()));
 714                             }
 715                         }
 716                     }
 717                     Some(..) | None => {}
 718                 }
 719             }
 720             _ => {}
 721         }
 722
 723         // Index this method for searching later on
 724         match item.name {
 725             Some(ref s) => {
 726                 let parent = match item.inner {
 727                     clean::TyMethodItem(..) |
 728                     clean::StructFieldItem(..) |
 729                     clean::VariantItem(..) => {
 730                         (Some(*self.parent_stack.last().unwrap()),
 731                          Some(self.stack.slice_to(self.stack.len() - 1)))
 732                     }
 733                     clean::MethodItem(..) => {
 734                         if self.parent_stack.len() == 0 {
 735                             (None, None)
 736                         } else {
 737                             let last = self.parent_stack.last().unwrap();
 738                             let did = *last;
 739                             let path = match self.paths.find(&did) {
 740                                 Some(&(_, item_type::Trait)) =>
 741                                     Some(self.stack.slice_to(self.stack.len() - 1)),
 742                                 // The current stack not necessarily has correlation for
 743                                 // where the type was defined. On the other hand,
 744                                 // `paths` always has the right information if present.
 745                                 Some(&(ref fqp, item_type::Struct)) |
 746                                 Some(&(ref fqp, item_type::Enum)) =>
 747                                     Some(fqp.slice_to(fqp.len() - 1)),
 748                                 Some(..) => Some(self.stack.as_slice()),
 749                                 None => None
 750                             };
 751                             (Some(*last), path)
 752                         }
 753                     }
 754                     _ => (None, Some(self.stack.as_slice()))
 755                 };
 756                 match parent {
 757                     (parent, Some(path)) if !self.privmod => {
 758                         self.search_index.push(IndexItem {
 759                             ty: shortty(&item),
 760                             name: s.to_strbuf(),
 761                             path: path.connect("::").to_strbuf(),
 762                             desc: shorter(item.doc_value()).to_strbuf(),
 763                             parent: parent,
 764                         });
 765                     }
 766                     (Some(parent), None) if !self.privmod => {
 767                         if ast_util::is_local(parent) {
 768                             // We have a parent, but we don't know where they're
 769                             // defined yet. Wait for later to index this item.
 770                             self.orphan_methods.push((parent.node, item.clone()))
 771                         }
 772                     }
 773                     _ => {}
 774                 }
 775             }
 776             None => {}
 777         }
 778
 779         // Keep track of the fully qualified path for this item.
 780         let pushed = if item.name.is_some() {
 781             let n = item.name.get_ref();
 782             if n.len() > 0 {
 783                 self.stack.push(n.to_strbuf());
 784                 true
 785             } else { false }
 786         } else { false };
 787         match item.inner {
 788             clean::StructItem(..) | clean::EnumItem(..) |
 789             clean::TypedefItem(..) | clean::TraitItem(..) |
 790             clean::FunctionItem(..) | clean::ModuleItem(..) |
 791             clean::ForeignFunctionItem(..) => {
 792                 // Reexported items mean that the same id can show up twice
 793                 // in the rustdoc ast that we're looking at. We know,
 794                 // however, that a reexported item doesn't show up in the
 795                 // `public_items` map, so we can skip inserting into the
 796                 // paths map if there was already an entry present and we're
 797                 // not a public item.
 798                 let id = item.def_id.node;
 799                 if !self.paths.contains_key(&item.def_id) ||
 800                    self.public_items.contains(&id) {
 801                     self.paths.insert(item.def_id,
 802                                       (self.stack.clone(), shortty(&item)));
 803                 }
 804             }
 805             // link variants to their parent enum because pages aren't emitted
 806             // for each variant
 807             clean::VariantItem(..) => {
 808                 let mut stack = self.stack.clone();
 809                 stack.pop();
 810                 self.paths.insert(item.def_id, (stack, item_type::Enum));
 811             }
 812             _ => {}
 813         }
 814
 815         // Maintain the parent stack
 816         let parent_pushed = match item.inner {
 817             clean::TraitItem(..) | clean::EnumItem(..) | clean::StructItem(..) => {
 818                 self.parent_stack.push(item.def_id);
 819                 true
 820             }
 821             clean::ImplItem(ref i) => {
 822                 match i.for_ {
 823                     clean::ResolvedPath{ did, .. } => {
 824                         self.parent_stack.push(did);
 825                         true
 826                     }
 827                     _ => false
 828                 }
 829             }
 830             _ => false
 831         };
 832
 833         // Once we've recursively found all the generics, then hoard off all the
 834         // implementations elsewhere
 835         let ret = match self.fold_item_recur(item) {
 836             Some(item) => {
 837                 match item {
 838                     clean::Item{ attrs, inner: clean::ImplItem(i), .. } => {
 839                         match i.for_ {
 840                             clean::ResolvedPath { did, .. } => {
 841                                 let v = self.impls.find_or_insert_with(did, |_| {
 842                                     Vec::new()
 843                                 });
 844                                 // extract relevant documentation for this impl
 845                                 match attrs.move_iter().find(|a| {
 846                                     match *a {
 847                                         clean::NameValue(ref x, _)
 848                                                 if "doc" == x.as_slice() => {
 849                                             true
 850                                         }
 851                                         _ => false
 852                                     }
 853                                 }) {
 854                                     Some(clean::NameValue(_, dox)) => {
 855                                         v.push((i, Some(dox)));
 856                                     }
 857                                     Some(..) | None => {
 858                                         v.push((i, None));
 859                                     }
 860                                 }
 861                             }
 862                             _ => {}
 863                         }
 864                         None
 865                     }
 866                     // Private modules may survive the strip-private pass if
 867                     // they contain impls for public types, but those will get
 868                     // stripped here
 869                     clean::Item { inner: clean::ModuleItem(ref m),
 870                                   visibility, .. }
 871                             if (m.items.len() == 0 &&
 872                                 item.doc_value().is_none()) ||
 873                                visibility != Some(ast::Public) => None,
 874
 875                     i => Some(i),
 876                 }
 877             }
 878             i => i,
 879         };
 880
 881         if pushed { self.stack.pop().unwrap(); }
 882         if parent_pushed { self.parent_stack.pop().unwrap(); }
 883         self.privmod = orig_privmod;
 884         return ret;
 885     }
 886 }
 887
 888 impl<'a> Cache {
 889     fn generics(&mut self, generics: &clean::Generics) {
 890         for typ in generics.type_params.iter() {
 891             self.typarams.insert(typ.did, typ.name.clone());
 892         }
 893     }
 894 }
 895
 896 impl Context {
 897     /// Recurse in the directory structure and change the "root path" to make
 898     /// sure it always points to the top (relatively)
 899     fn recurse<T>(&mut self, s: String, f: |&mut Context| -> T) -> T {
 900         if s.len() == 0 {
 901             fail!("what {:?}", self);
 902         }
 903         let prev = self.dst.clone();
 904         self.dst.push(s.as_slice());
 905         self.root_path.push_str("../");
 906         self.current.push(s);
 907
 908         info!("Recursing into {}", self.dst.display());
 909
 910         mkdir(&self.dst).unwrap();
 911         let ret = f(self);
 912
 913         info!("Recursed; leaving {}", self.dst.display());
 914
 915         // Go back to where we were at
 916         self.dst = prev;
 917         let len = self.root_path.len();
 918         self.root_path.truncate(len - 3);
 919         self.current.pop().unwrap();
 920
 921         return ret;
 922     }
 923
 924     /// Main method for rendering a crate.
 925     ///
 926     /// This currently isn't parallelized, but it'd be pretty easy to add
 927     /// parallelization to this function.
 928     fn krate(self, mut krate: clean::Crate, cache: Cache) -> io::IoResult<()> {
 929         let mut item = match krate.module.take() {
 930             Some(i) => i,
 931             None => return Ok(())
 932         };
 933         item.name = Some(krate.name);
 934
 935         // using a rwarc makes this parallelizable in the future
 936         cache_key.replace(Some(Arc::new(cache)));
 937
 938         let mut work = vec!((self, item));
 939         loop {
 940             match work.pop() {
 941                 Some((mut cx, item)) => try!(cx.item(item, |cx, item| {
 942                     work.push((cx.clone(), item));
 943                 })),
 944                 None => break,
 945             }
 946         }
 947         Ok(())
 948     }
 949
 950     /// Non-parellelized version of rendering an item. This will take the input
 951     /// item, render its contents, and then invoke the specified closure with
 952     /// all sub-items which need to be rendered.
 953     ///
 954     /// The rendering driver uses this closure to queue up more work.
 955     fn item(&mut self, item: clean::Item,
 956             f: |&mut Context, clean::Item|) -> io::IoResult<()> {
 957         fn render(w: io::File, cx: &mut Context, it: &clean::Item,
 958                   pushname: bool) -> io::IoResult<()> {
 959             info!("Rendering an item to {}", w.path().display());
 960             // A little unfortunate that this is done like this, but it sure
 961             // does make formatting *a lot* nicer.
 962             current_location_key.replace(Some(cx.current.clone()));
 963
 964             let mut title = cx.current.connect("::");
 965             if pushname {
 966                 if title.len() > 0 {
 967                     title.push_str("::");
 968                 }
 969                 title.push_str(it.name.get_ref().as_slice());
 970             }
 971             title.push_str(" - Rust");
 972             let page = layout::Page {
 973                 ty: shortty(it).to_static_str(),
 974                 root_path: cx.root_path.as_slice(),
 975                 title: title.as_slice(),
 976             };
 977
 978             markdown::reset_headers();
 979
 980             // We have a huge number of calls to write, so try to alleviate some
 981             // of the pain by using a buffered writer instead of invoking the
 982             // write sycall all the time.
 983             let mut writer = BufferedWriter::new(w);
 984             try!(layout::render(&mut writer as &mut Writer, &cx.layout, &page,
 985                                 &Sidebar{ cx: cx, item: it },
 986                                 &Item{ cx: cx, item: it }));
 987             writer.flush()
 988         }
 989
 990         match item.inner {
 991             // modules are special because they add a namespace. We also need to
 992             // recurse into the items of the module as well.
 993             clean::ModuleItem(..) => {
 994                 let name = item.name.get_ref().to_strbuf();
 995                 let mut item = Some(item);
 996                 self.recurse(name, |this| {
 997                     let item = item.take_unwrap();
 998                     let dst = this.dst.join("index.html");
 999                     let dst = try!(File::create(&dst));
1000                     try!(render(dst, this, &item, false));
1001
1002                     let m = match item.inner {
1003                         clean::ModuleItem(m) => m,
1004                         _ => unreachable!()
1005                     };
1006                     this.sidebar = build_sidebar(&m);
1007                     for item in m.items.move_iter() {
1008                         f(this,item);
1009                     }
1010                     Ok(())
1011                 })
1012             }
1013
1014             // Things which don't have names (like impls) don't get special
1015             // pages dedicated to them.
1016             _ if item.name.is_some() => {
1017                 let dst = self.dst.join(item_path(&item));
1018                 let dst = try!(File::create(&dst));
1019                 render(dst, self, &item, true)
1020             }
1021
1022             _ => Ok(())
1023         }
1024     }
1025 }
1026
1027 impl<'a> Item<'a> {
1028     fn ismodule(&self) -> bool {
1029         match self.item.inner {
1030             clean::ModuleItem(..) => true, _ => false
1031         }
1032     }
1033
1034     fn link(&self) -> String {
1035         let mut path = Vec::new();
1036         clean_srcpath(self.item.source.filename.as_bytes(), |component| {
1037             path.push(component.to_owned());
1038         });
1039         let href = if self.item.source.loline == self.item.source.hiline {
1040             format_strbuf!("{}", self.item.source.loline)
1041         } else {
1042             format_strbuf!("{}-{}",
1043                            self.item.source.loline,
1044                            self.item.source.hiline)
1045         };
1046         format_strbuf!("{root}src/{krate}/{path}.html\\#{href}",
1047                        root = self.cx.root_path,
1048                        krate = self.cx.layout.krate,
1049                        path = path.connect("/"),
1050                        href = href)
1051     }
1052 }
1053
1054 impl<'a> fmt::Show for Item<'a> {
1055     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1056         // Write the breadcrumb trail header for the top
1057         try!(write!(fmt, "\n<h1 class='fqn'>"));
1058         match self.item.inner {
1059             clean::ModuleItem(ref m) => if m.is_crate {
1060                     try!(write!(fmt, "Crate "));
1061                 } else {
1062                     try!(write!(fmt, "Module "));
1063                 },
1064             clean::FunctionItem(..) => try!(write!(fmt, "Function ")),
1065             clean::TraitItem(..) => try!(write!(fmt, "Trait ")),
1066             clean::StructItem(..) => try!(write!(fmt, "Struct ")),
1067             clean::EnumItem(..) => try!(write!(fmt, "Enum ")),
1068             _ => {}
1069         }
1070         let cur = self.cx.current.as_slice();
1071         let amt = if self.ismodule() { cur.len() - 1 } else { cur.len() };
1072         for (i, component) in cur.iter().enumerate().take(amt) {
1073             let mut trail = String::new();
1074             for _ in range(0, cur.len() - i - 1) {
1075                 trail.push_str("../");
1076             }
1077             try!(write!(fmt, "<a href='{}index.html'>{}</a>::",
1078                         trail, component.as_slice()));
1079         }
1080         try!(write!(fmt, "<a class='{}' href=''>{}</a>",
1081                     shortty(self.item), self.item.name.get_ref().as_slice()));
1082
1083         // Write stability attributes
1084         match attr::find_stability_generic(self.item.attrs.iter()) {
1085             Some((ref stability, _)) => {
1086                 try!(write!(fmt,
1087                        "<a class='stability {lvl}' title='{reason}'>{lvl}</a>",
1088                        lvl = stability.level.to_str(),
1089                        reason = match stability.text {
1090                            Some(ref s) => (*s).clone(),
1091                            None => InternedString::new(""),
1092                        }));
1093             }
1094             None => {}
1095         }
1096
1097         // Write `src` tag
1098         if self.cx.include_sources {
1099             try!(write!(fmt, "<a class='source' href='{}'>[src]</a>",
1100                         self.link()));
1101         }
1102         try!(write!(fmt, "</h1>\n"));
1103
1104         match self.item.inner {
1105             clean::ModuleItem(ref m) => {
1106                 item_module(fmt, self.cx, self.item, m.items.as_slice())
1107             }
1108             clean::FunctionItem(ref f) | clean::ForeignFunctionItem(ref f) =>
1109                 item_function(fmt, self.item, f),
1110             clean::TraitItem(ref t) => item_trait(fmt, self.cx, self.item, t),
1111             clean::StructItem(ref s) => item_struct(fmt, self.item, s),
1112             clean::EnumItem(ref e) => item_enum(fmt, self.item, e),
1113             clean::TypedefItem(ref t) => item_typedef(fmt, self.item, t),
1114             clean::MacroItem(ref m) => item_macro(fmt, self.item, m),
1115             _ => Ok(())
1116         }
1117     }
1118 }
1119
1120 fn item_path(item: &clean::Item) -> String {
1121     match item.inner {
1122         clean::ModuleItem(..) => {
1123             format_strbuf!("{}/index.html", item.name.get_ref())
1124         }
1125         _ => {
1126             format_strbuf!("{}.{}.html",
1127                            shortty(item).to_static_str(),
1128                            *item.name.get_ref())
1129         }
1130     }
1131 }
1132
1133 fn full_path(cx: &Context, item: &clean::Item) -> String {
1134     let mut s = cx.current.connect("::");
1135     s.push_str("::");
1136     s.push_str(item.name.get_ref().as_slice());
1137     return s
1138 }
1139
1140 fn blank<'a>(s: Option<&'a str>) -> &'a str {
1141     match s {
1142         Some(s) => s,
1143         None => ""
1144     }
1145 }
1146
1147 fn shorter<'a>(s: Option<&'a str>) -> &'a str {
1148     match s {
1149         Some(s) => match s.find_str("\n\n") {
1150             Some(pos) => s.slice_to(pos),
1151             None => s,
1152         },
1153         None => ""
1154     }
1155 }
1156
1157 fn document(w: &mut fmt::Formatter, item: &clean::Item) -> fmt::Result {
1158     match item.doc_value() {
1159         Some(s) => {
1160             try!(write!(w, "<div class='docblock'>{}</div>", Markdown(s)));
1161         }
1162         None => {}
1163     }
1164     Ok(())
1165 }
1166
1167 fn item_module(w: &mut fmt::Formatter, cx: &Context,
1168                item: &clean::Item, items: &[clean::Item]) -> fmt::Result {
1169     try!(document(w, item));
1170     debug!("{:?}", items);
1171     let mut indices = Vec::from_fn(items.len(), |i| i);
1172
1173     fn cmp(i1: &clean::Item, i2: &clean::Item, idx1: uint, idx2: uint) -> Ordering {
1174         if shortty(i1) == shortty(i2) {
1175             return i1.name.cmp(&i2.name);
1176         }
1177         match (&i1.inner, &i2.inner) {
1178             (&clean::ViewItemItem(ref a), &clean::ViewItemItem(ref b)) => {
1179                 match (&a.inner, &b.inner) {
1180                     (&clean::ExternCrate(..), _) => Less,
1181                     (_, &clean::ExternCrate(..)) => Greater,
1182                     _ => idx1.cmp(&idx2),
1183                 }
1184             }
1185             (&clean::ViewItemItem(..), _) => Less,
1186             (_, &clean::ViewItemItem(..)) => Greater,
1187             (&clean::ModuleItem(..), _) => Less,
1188             (_, &clean::ModuleItem(..)) => Greater,
1189             (&clean::MacroItem(..), _) => Less,
1190             (_, &clean::MacroItem(..)) => Greater,
1191             (&clean::StructItem(..), _) => Less,
1192             (_, &clean::StructItem(..)) => Greater,
1193             (&clean::EnumItem(..), _) => Less,
1194             (_, &clean::EnumItem(..)) => Greater,
1195             (&clean::StaticItem(..), _) => Less,
1196             (_, &clean::StaticItem(..)) => Greater,
1197             (&clean::ForeignFunctionItem(..), _) => Less,
1198             (_, &clean::ForeignFunctionItem(..)) => Greater,
1199             (&clean::ForeignStaticItem(..), _) => Less,
1200             (_, &clean::ForeignStaticItem(..)) => Greater,
1201             (&clean::TraitItem(..), _) => Less,
1202             (_, &clean::TraitItem(..)) => Greater,
1203             (&clean::FunctionItem(..), _) => Less,
1204             (_, &clean::FunctionItem(..)) => Greater,
1205             (&clean::TypedefItem(..), _) => Less,
1206             (_, &clean::TypedefItem(..)) => Greater,
1207             _ => idx1.cmp(&idx2),
1208         }
1209     }
1210
1211     debug!("{:?}", indices);
1212     indices.sort_by(|&i1, &i2| cmp(&items[i1], &items[i2], i1, i2));
1213
1214     debug!("{:?}", indices);
1215     let mut curty = None;
1216     for &idx in indices.iter() {
1217         let myitem = &items[idx];
1218
1219         let myty = Some(shortty(myitem));
1220         if myty != curty {
1221             if curty.is_some() {
1222                 try!(write!(w, "</table>"));
1223             }
1224             curty = myty;
1225             let (short, name) = match myitem.inner {
1226                 clean::ModuleItem(..)          => ("modules", "Modules"),
1227                 clean::StructItem(..)          => ("structs", "Structs"),
1228                 clean::EnumItem(..)            => ("enums", "Enums"),
1229                 clean::FunctionItem(..)        => ("functions", "Functions"),
1230                 clean::TypedefItem(..)         => ("types", "Type Definitions"),
1231                 clean::StaticItem(..)          => ("statics", "Statics"),
1232                 clean::TraitItem(..)           => ("traits", "Traits"),
1233                 clean::ImplItem(..)            => ("impls", "Implementations"),
1234                 clean::ViewItemItem(..)        => ("reexports", "Reexports"),
1235                 clean::TyMethodItem(..)        => ("tymethods", "Type Methods"),
1236                 clean::MethodItem(..)          => ("methods", "Methods"),
1237                 clean::StructFieldItem(..)     => ("fields", "Struct Fields"),
1238                 clean::VariantItem(..)         => ("variants", "Variants"),
1239                 clean::ForeignFunctionItem(..) => ("ffi-fns", "Foreign Functions"),
1240                 clean::ForeignStaticItem(..)   => ("ffi-statics", "Foreign Statics"),
1241                 clean::MacroItem(..)           => ("macros", "Macros"),
1242             };
1243             try!(write!(w,
1244                         "<h2 id='{id}' class='section-header'>\
1245                         <a href=\"\\#{id}\">{name}</a></h2>\n<table>",
1246                         id = short, name = name));
1247         }
1248
1249         match myitem.inner {
1250             clean::StaticItem(ref s) | clean::ForeignStaticItem(ref s) => {
1251                 struct Initializer<'a>(&'a str, Item<'a>);
1252                 impl<'a> fmt::Show for Initializer<'a> {
1253                     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
1254                         let Initializer(s, item) = *self;
1255                         if s.len() == 0 { return Ok(()); }
1256                         try!(write!(f, "<code> = </code>"));
1257                         if s.contains("\n") {
1258                             write!(f, "<a href='{}'>[definition]</a>",
1259                                    item.link())
1260                         } else {
1261                             write!(f, "<code>{}</code>", s.as_slice())
1262                         }
1263                     }
1264                 }
1265
1266                 try!(write!(w, "
1267                     <tr>
1268                         <td><code>{}static {}: {}</code>{}</td>
1269                         <td class='docblock'>{}&nbsp;</td>
1270                     </tr>
1271                 ",
1272                 VisSpace(myitem.visibility),
1273                 *myitem.name.get_ref(),
1274                 s.type_,
1275                 Initializer(s.expr.as_slice(), Item { cx: cx, item: myitem }),
1276                 Markdown(blank(myitem.doc_value()))));
1277             }
1278
1279             clean::ViewItemItem(ref item) => {
1280                 match item.inner {
1281                     clean::ExternCrate(ref name, ref src, _) => {
1282                         try!(write!(w, "<tr><td><code>extern crate {}",
1283                                       name.as_slice()));
1284                         match *src {
1285                             Some(ref src) => try!(write!(w, " = \"{}\"",
1286                                                            src.as_slice())),
1287                             None => {}
1288                         }
1289                         try!(write!(w, ";</code></td></tr>"));
1290                     }
1291
1292                     clean::Import(ref import) => {
1293                         try!(write!(w, "<tr><td><code>{}{}</code></td></tr>",
1294                                       VisSpace(myitem.visibility),
1295                                       *import));
1296                     }
1297                 }
1298
1299             }
1300
1301             _ => {
1302                 if myitem.name.is_none() { continue }
1303                 try!(write!(w, "
1304                     <tr>
1305                         <td><a class='{class}' href='{href}'
1306                                title='{title}'>{}</a></td>
1307                         <td class='docblock short'>{}</td>
1308                     </tr>
1309                 ",
1310                 *myitem.name.get_ref(),
1311                 Markdown(shorter(myitem.doc_value())),
1312                 class = shortty(myitem),
1313                 href = item_path(myitem),
1314                 title = full_path(cx, myitem)));
1315             }
1316         }
1317     }
1318     write!(w, "</table>")
1319 }
1320
1321 fn item_function(w: &mut fmt::Formatter, it: &clean::Item,
1322                  f: &clean::Function) -> fmt::Result {
1323     try!(write!(w, "<pre class='rust fn'>{vis}{fn_style}fn \
1324                     {name}{generics}{decl}</pre>",
1325            vis = VisSpace(it.visibility),
1326            fn_style = FnStyleSpace(f.fn_style),
1327            name = it.name.get_ref().as_slice(),
1328            generics = f.generics,
1329            decl = f.decl));
1330     document(w, it)
1331 }
1332
1333 fn item_trait(w: &mut fmt::Formatter, cx: &Context, it: &clean::Item,
1334               t: &clean::Trait) -> fmt::Result {
1335     let mut parents = String::new();
1336     if t.parents.len() > 0 {
1337         parents.push_str(": ");
1338         for (i, p) in t.parents.iter().enumerate() {
1339             if i > 0 { parents.push_str(" + "); }
1340             parents.push_str(format!("{}", *p).as_slice());
1341         }
1342     }
1343
1344     // Output the trait definition
1345     try!(write!(w, "<pre class='rust trait'>{}trait {}{}{} ",
1346                   VisSpace(it.visibility),
1347                   it.name.get_ref().as_slice(),
1348                   t.generics,
1349                   parents));
1350     let required = t.methods.iter().filter(|m| m.is_req()).collect::<Vec<&clean::TraitMethod>>();
1351     let provided = t.methods.iter().filter(|m| !m.is_req()).collect::<Vec<&clean::TraitMethod>>();
1352
1353     if t.methods.len() == 0 {
1354         try!(write!(w, "\\{ \\}"));
1355     } else {
1356         try!(write!(w, "\\{\n"));
1357         for m in required.iter() {
1358             try!(write!(w, "    "));
1359             try!(render_method(w, m.item()));
1360             try!(write!(w, ";\n"));
1361         }
1362         if required.len() > 0 && provided.len() > 0 {
1363             try!(w.write("\n".as_bytes()));
1364         }
1365         for m in provided.iter() {
1366             try!(write!(w, "    "));
1367             try!(render_method(w, m.item()));
1368             try!(write!(w, " \\{ ... \\}\n"));
1369         }
1370         try!(write!(w, "\\}"));
1371     }
1372     try!(write!(w, "</pre>"));
1373
1374     // Trait documentation
1375     try!(document(w, it));
1376
1377     fn meth(w: &mut fmt::Formatter, m: &clean::TraitMethod) -> fmt::Result {
1378         try!(write!(w, "<h3 id='{}.{}' class='method'><code>",
1379                       shortty(m.item()),
1380                       *m.item().name.get_ref()));
1381         try!(render_method(w, m.item()));
1382         try!(write!(w, "</code></h3>"));
1383         try!(document(w, m.item()));
1384         Ok(())
1385     }
1386
1387     // Output the documentation for each function individually
1388     if required.len() > 0 {
1389         try!(write!(w, "
1390             <h2 id='required-methods'>Required Methods</h2>
1391             <div class='methods'>
1392         "));
1393         for m in required.iter() {
1394             try!(meth(w, *m));
1395         }
1396         try!(write!(w, "</div>"));
1397     }
1398     if provided.len() > 0 {
1399         try!(write!(w, "
1400             <h2 id='provided-methods'>Provided Methods</h2>
1401             <div class='methods'>
1402         "));
1403         for m in provided.iter() {
1404             try!(meth(w, *m));
1405         }
1406         try!(write!(w, "</div>"));
1407     }
1408
1409     match cache_key.get().unwrap().implementors.find(&it.def_id) {
1410         Some(implementors) => {
1411             try!(write!(w, "
1412                 <h2 id='implementors'>Implementors</h2>
1413                 <ul class='item-list' id='implementors-list'>
1414             "));
1415             for i in implementors.iter() {
1416                 match *i {
1417                     PathType(ref ty) => {
1418                         try!(write!(w, "<li><code>{}</code></li>", *ty));
1419                     }
1420                     OtherType(ref generics, ref trait_, ref for_) => {
1421                         try!(write!(w, "<li><code>impl{} {} for {}</code></li>",
1422                                       *generics, *trait_, *for_));
1423                     }
1424                 }
1425             }
1426             try!(write!(w, "</ul>"));
1427             try!(write!(w, r#"<script type="text/javascript" async
1428                                       src="{}/implementors/{}/{}.{}.js"></script>"#,
1429                         cx.current.iter().map(|_| "..")
1430                                   .collect::<Vec<&str>>().connect("/"),
1431                         cx.current.connect("/"),
1432                         shortty(it).to_static_str(),
1433                         *it.name.get_ref()));
1434         }
1435         None => {}
1436     }
1437     Ok(())
1438 }
1439
1440 fn render_method(w: &mut fmt::Formatter, meth: &clean::Item) -> fmt::Result {
1441     fn fun(w: &mut fmt::Formatter, it: &clean::Item, fn_style: ast::FnStyle,
1442            g: &clean::Generics, selfty: &clean::SelfTy,
1443            d: &clean::FnDecl) -> fmt::Result {
1444         write!(w, "{}fn <a href='\\#{ty}.{name}' class='fnname'>{name}</a>\
1445                    {generics}{decl}",
1446                match fn_style {
1447                    ast::UnsafeFn => "unsafe ",
1448                    _ => "",
1449                },
1450                ty = shortty(it),
1451                name = it.name.get_ref().as_slice(),
1452                generics = *g,
1453                decl = Method(selfty, d))
1454     }
1455     match meth.inner {
1456         clean::TyMethodItem(ref m) => {
1457             fun(w, meth, m.fn_style, &m.generics, &m.self_, &m.decl)
1458         }
1459         clean::MethodItem(ref m) => {
1460             fun(w, meth, m.fn_style, &m.generics, &m.self_, &m.decl)
1461         }
1462         _ => unreachable!()
1463     }
1464 }
1465
1466 fn item_struct(w: &mut fmt::Formatter, it: &clean::Item,
1467                s: &clean::Struct) -> fmt::Result {
1468     try!(write!(w, "<pre class='rust struct'>"));
1469     try!(render_struct(w,
1470                        it,
1471                        Some(&s.generics),
1472                        s.struct_type,
1473                        s.fields.as_slice(),
1474                        "",
1475                        true));
1476     try!(write!(w, "</pre>"));
1477
1478     try!(document(w, it));
1479     let mut fields = s.fields.iter().filter(|f| {
1480         match f.inner {
1481             clean::StructFieldItem(clean::HiddenStructField) => false,
1482             clean::StructFieldItem(clean::TypedStructField(..)) => true,
1483             _ => false,
1484         }
1485     }).peekable();
1486     match s.struct_type {
1487         doctree::Plain if fields.peek().is_some() => {
1488             try!(write!(w, "<h2 class='fields'>Fields</h2>\n<table>"));
1489             for field in fields {
1490                 try!(write!(w, "<tr><td id='structfield.{name}'>\
1491                                   <code>{name}</code></td><td>",
1492                               name = field.name.get_ref().as_slice()));
1493                 try!(document(w, field));
1494                 try!(write!(w, "</td></tr>"));
1495             }
1496             try!(write!(w, "</table>"));
1497         }
1498         _ => {}
1499     }
1500     render_methods(w, it)
1501 }
1502
1503 fn item_enum(w: &mut fmt::Formatter, it: &clean::Item,
1504              e: &clean::Enum) -> fmt::Result {
1505     try!(write!(w, "<pre class='rust enum'>{}enum {}{}",
1506                   VisSpace(it.visibility),
1507                   it.name.get_ref().as_slice(),
1508                   e.generics));
1509     if e.variants.len() == 0 && !e.variants_stripped {
1510         try!(write!(w, " \\{\\}"));
1511     } else {
1512         try!(write!(w, " \\{\n"));
1513         for v in e.variants.iter() {
1514             try!(write!(w, "    "));
1515             let name = v.name.get_ref().as_slice();
1516             match v.inner {
1517                 clean::VariantItem(ref var) => {
1518                     match var.kind {
1519                         clean::CLikeVariant => try!(write!(w, "{}", name)),
1520                         clean::TupleVariant(ref tys) => {
1521                             try!(write!(w, "{}(", name));
1522                             for (i, ty) in tys.iter().enumerate() {
1523                                 if i > 0 {
1524                                     try!(write!(w, ", "))
1525                                 }
1526                                 try!(write!(w, "{}", *ty));
1527                             }
1528                             try!(write!(w, ")"));
1529                         }
1530                         clean::StructVariant(ref s) => {
1531                             try!(render_struct(w,
1532                                                v,
1533                                                None,
1534                                                s.struct_type,
1535                                                s.fields.as_slice(),
1536                                                "    ",
1537                                                false));
1538                         }
1539                     }
1540                 }
1541                 _ => unreachable!()
1542             }
1543             try!(write!(w, ",\n"));
1544         }
1545
1546         if e.variants_stripped {
1547             try!(write!(w, "    // some variants omitted\n"));
1548         }
1549         try!(write!(w, "\\}"));
1550     }
1551     try!(write!(w, "</pre>"));
1552
1553     try!(document(w, it));
1554     if e.variants.len() > 0 {
1555         try!(write!(w, "<h2 class='variants'>Variants</h2>\n<table>"));
1556         for variant in e.variants.iter() {
1557             try!(write!(w, "<tr><td id='variant.{name}'><code>{name}</code></td><td>",
1558                           name = variant.name.get_ref().as_slice()));
1559             try!(document(w, variant));
1560             match variant.inner {
1561                 clean::VariantItem(ref var) => {
1562                     match var.kind {
1563                         clean::StructVariant(ref s) => {
1564                             let mut fields = s.fields.iter().filter(|f| {
1565                                 match f.inner {
1566                                     clean::StructFieldItem(ref t) => match *t {
1567                                         clean::HiddenStructField => false,
1568                                         clean::TypedStructField(..) => true,
1569                                     },
1570                                     _ => false,
1571                                 }
1572                             });
1573                             try!(write!(w, "<h3 class='fields'>Fields</h3>\n
1574                                               <table>"));
1575                             for field in fields {
1576                                 try!(write!(w, "<tr><td \
1577                                                   id='variant.{v}.field.{f}'>\
1578                                                   <code>{f}</code></td><td>",
1579                                               v = variant.name.get_ref().as_slice(),
1580                                               f = field.name.get_ref().as_slice()));
1581                                 try!(document(w, field));
1582                                 try!(write!(w, "</td></tr>"));
1583                             }
1584                             try!(write!(w, "</table>"));
1585                         }
1586                         _ => ()
1587                     }
1588                 }
1589                 _ => ()
1590             }
1591             try!(write!(w, "</td></tr>"));
1592         }
1593         try!(write!(w, "</table>"));
1594
1595     }
1596     try!(render_methods(w, it));
1597     Ok(())
1598 }
1599
1600 fn render_struct(w: &mut fmt::Formatter, it: &clean::Item,
1601                  g: Option<&clean::Generics>,
1602                  ty: doctree::StructType,
1603                  fields: &[clean::Item],
1604                  tab: &str,
1605                  structhead: bool) -> fmt::Result {
1606     try!(write!(w, "{}{}{}",
1607                   VisSpace(it.visibility),
1608                   if structhead {"struct "} else {""},
1609                   it.name.get_ref().as_slice()));
1610     match g {
1611         Some(g) => try!(write!(w, "{}", *g)),
1612         None => {}
1613     }
1614     match ty {
1615         doctree::Plain => {
1616             try!(write!(w, " \\{\n{}", tab));
1617             let mut fields_stripped = false;
1618             for field in fields.iter() {
1619                 match field.inner {
1620                     clean::StructFieldItem(clean::HiddenStructField) => {
1621                         fields_stripped = true;
1622                     }
1623                     clean::StructFieldItem(clean::TypedStructField(ref ty)) => {
1624                         try!(write!(w, "    {}{}: {},\n{}",
1625                                       VisSpace(field.visibility),
1626                                       field.name.get_ref().as_slice(),
1627                                       *ty,
1628                                       tab));
1629                     }
1630                     _ => unreachable!(),
1631                 };
1632             }
1633
1634             if fields_stripped {
1635                 try!(write!(w, "    // some fields omitted\n{}", tab));
1636             }
1637             try!(write!(w, "\\}"));
1638         }
1639         doctree::Tuple | doctree::Newtype => {
1640             try!(write!(w, "("));
1641             for (i, field) in fields.iter().enumerate() {
1642                 if i > 0 {
1643                     try!(write!(w, ", "));
1644                 }
1645                 match field.inner {
1646                     clean::StructFieldItem(clean::HiddenStructField) => {
1647                         try!(write!(w, "_"))
1648                     }
1649                     clean::StructFieldItem(clean::TypedStructField(ref ty)) => {
1650                         try!(write!(w, "{}{}", VisSpace(field.visibility), *ty))
1651                     }
1652                     _ => unreachable!()
1653                 }
1654             }
1655             try!(write!(w, ");"));
1656         }
1657         doctree::Unit => {
1658             try!(write!(w, ";"));
1659         }
1660     }
1661     Ok(())
1662 }
1663
1664 fn render_methods(w: &mut fmt::Formatter, it: &clean::Item) -> fmt::Result {
1665     match cache_key.get().unwrap().impls.find(&it.def_id) {
1666         Some(v) => {
1667             let mut non_trait = v.iter().filter(|p| {
1668                 p.ref0().trait_.is_none()
1669             });
1670             let non_trait = non_trait.collect::<Vec<&(clean::Impl, Option<String>)>>();
1671             let mut traits = v.iter().filter(|p| {
1672                 p.ref0().trait_.is_some()
1673             });
1674             let traits = traits.collect::<Vec<&(clean::Impl, Option<String>)>>();
1675
1676             if non_trait.len() > 0 {
1677                 try!(write!(w, "<h2 id='methods'>Methods</h2>"));
1678                 for &(ref i, ref dox) in non_trait.move_iter() {
1679                     try!(render_impl(w, i, dox));
1680                 }
1681             }
1682             if traits.len() > 0 {
1683                 try!(write!(w, "<h2 id='implementations'>Trait \
1684                                   Implementations</h2>"));
1685                 let mut any_derived = false;
1686                 for & &(ref i, ref dox) in traits.iter() {
1687                     if !i.derived {
1688                         try!(render_impl(w, i, dox));
1689                     } else {
1690                         any_derived = true;
1691                     }
1692                 }
1693                 if any_derived {
1694                     try!(write!(w, "<h3 id='derived_implementations'>Derived Implementations \
1695                                 </h3>"));
1696                     for &(ref i, ref dox) in traits.move_iter() {
1697                         if i.derived {
1698                             try!(render_impl(w, i, dox));
1699                         }
1700                     }
1701                 }
1702             }
1703         }
1704         None => {}
1705     }
1706     Ok(())
1707 }
1708
1709 fn render_impl(w: &mut fmt::Formatter, i: &clean::Impl,
1710                dox: &Option<String>) -> fmt::Result {
1711     try!(write!(w, "<h3 class='impl'><code>impl{} ", i.generics));
1712     match i.trait_ {
1713         Some(ref ty) => try!(write!(w, "{} for ", *ty)),
1714         None => {}
1715     }
1716     try!(write!(w, "{}</code></h3>", i.for_));
1717     match *dox {
1718         Some(ref dox) => {
1719             try!(write!(w, "<div class='docblock'>{}</div>",
1720                           Markdown(dox.as_slice())));
1721         }
1722         None => {}
1723     }
1724
1725     fn docmeth(w: &mut fmt::Formatter, item: &clean::Item,
1726                dox: bool) -> fmt::Result {
1727         try!(write!(w, "<h4 id='method.{}' class='method'><code>",
1728                       *item.name.get_ref()));
1729         try!(render_method(w, item));
1730         try!(write!(w, "</code></h4>\n"));
1731         match item.doc_value() {
1732             Some(s) if dox => {
1733                 try!(write!(w, "<div class='docblock'>{}</div>", Markdown(s)));
1734                 Ok(())
1735             }
1736             Some(..) | None => Ok(())
1737         }
1738     }
1739
1740     try!(write!(w, "<div class='methods'>"));
1741     for meth in i.methods.iter() {
1742         try!(docmeth(w, meth, true));
1743     }
1744
1745     fn render_default_methods(w: &mut fmt::Formatter,
1746                               t: &clean::Trait,
1747                               i: &clean::Impl) -> fmt::Result {
1748         for method in t.methods.iter() {
1749             let n = method.item().name.clone();
1750             match i.methods.iter().find(|m| { m.name == n }) {
1751                 Some(..) => continue,
1752                 None => {}
1753             }
1754
1755             try!(docmeth(w, method.item(), false));
1756         }
1757         Ok(())
1758     }
1759
1760     // If we've implemented a trait, then also emit documentation for all
1761     // default methods which weren't overridden in the implementation block.
1762     match i.trait_ {
1763         Some(clean::ResolvedPath { did, .. }) => {
1764             try!({
1765                 match cache_key.get().unwrap().traits.find(&did) {
1766                     Some(t) => try!(render_default_methods(w, t, i)),
1767                     None => {}
1768                 }
1769                 Ok(())
1770             })
1771         }
1772         Some(..) | None => {}
1773     }
1774     try!(write!(w, "</div>"));
1775     Ok(())
1776 }
1777
1778 fn item_typedef(w: &mut fmt::Formatter, it: &clean::Item,
1779                 t: &clean::Typedef) -> fmt::Result {
1780     try!(write!(w, "<pre class='rust typedef'>type {}{} = {};</pre>",
1781                   it.name.get_ref().as_slice(),
1782                   t.generics,
1783                   t.type_));
1784
1785     document(w, it)
1786 }
1787
1788 impl<'a> fmt::Show for Sidebar<'a> {
1789     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1790         let cx = self.cx;
1791         let it = self.item;
1792         try!(write!(fmt, "<p class='location'>"));
1793         let len = cx.current.len() - if it.is_mod() {1} else {0};
1794         for (i, name) in cx.current.iter().take(len).enumerate() {
1795             if i > 0 {
1796                 try!(write!(fmt, "&\\#8203;::"));
1797             }
1798             try!(write!(fmt, "<a href='{}index.html'>{}</a>",
1799                           cx.root_path
1800                             .as_slice()
1801                             .slice_to((cx.current.len() - i - 1) * 3),
1802                           *name));
1803         }
1804         try!(write!(fmt, "</p>"));
1805
1806         fn block(w: &mut fmt::Formatter, short: &str, longty: &str,
1807                  cur: &clean::Item, cx: &Context) -> fmt::Result {
1808             let items = match cx.sidebar.find_equiv(&short) {
1809                 Some(items) => items.as_slice(),
1810                 None => return Ok(())
1811             };
1812             try!(write!(w, "<div class='block {}'><h2>{}</h2>", short, longty));
1813             for item in items.iter() {
1814                 let curty = shortty(cur).to_static_str();
1815                 let class = if cur.name.get_ref() == item &&
1816                                short == curty { "current" } else { "" };
1817                 try!(write!(w, "<a class='{ty} {class}' href='{curty, select,
1818                                 mod{../}
1819                                 other{}
1820                            }{tysel, select,
1821                                 mod{{name}/index.html}
1822                                 other{#.{name}.html}
1823                            }'>{name}</a><br/>",
1824                        ty = short,
1825                        tysel = short,
1826                        class = class,
1827                        curty = curty,
1828                        name = item.as_slice()));
1829             }
1830             try!(write!(w, "</div>"));
1831             Ok(())
1832         }
1833
1834         try!(block(fmt, "mod", "Modules", it, cx));
1835         try!(block(fmt, "struct", "Structs", it, cx));
1836         try!(block(fmt, "enum", "Enums", it, cx));
1837         try!(block(fmt, "trait", "Traits", it, cx));
1838         try!(block(fmt, "fn", "Functions", it, cx));
1839         try!(block(fmt, "macro", "Macros", it, cx));
1840         Ok(())
1841     }
1842 }
1843
1844 fn build_sidebar(m: &clean::Module) -> HashMap<String, Vec<String>> {
1845     let mut map = HashMap::new();
1846     for item in m.items.iter() {
1847         let short = shortty(item).to_static_str();
1848         let myname = match item.name {
1849             None => continue,
1850             Some(ref s) => s.to_strbuf(),
1851         };
1852         let v = map.find_or_insert_with(short.to_strbuf(), |_| Vec::new());
1853         v.push(myname);
1854     }
1855
1856     for (_, items) in map.mut_iter() {
1857         items.as_mut_slice().sort();
1858     }
1859     return map;
1860 }
1861
1862 impl<'a> fmt::Show for Source<'a> {
1863     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
1864         let Source(s) = *self;
1865         let lines = s.lines().len();
1866         let mut cols = 0;
1867         let mut tmp = lines;
1868         while tmp > 0 {
1869             cols += 1;
1870             tmp /= 10;
1871         }
1872         try!(write!(fmt, "<pre class='line-numbers'>"));
1873         for i in range(1, lines + 1) {
1874             try!(write!(fmt, "<span id='{0:u}'>{0:1$u}</span>\n", i, cols));
1875         }
1876         try!(write!(fmt, "</pre>"));
1877         try!(write!(fmt, "{}", highlight::highlight(s.as_slice(), None)));
1878         Ok(())
1879     }
1880 }
1881
1882 fn item_macro(w: &mut fmt::Formatter, it: &clean::Item,
1883               t: &clean::Macro) -> fmt::Result {
1884     try!(w.write(highlight::highlight(t.source.as_slice(), Some("macro")).as_bytes()));
1885     document(w, it)
1886 }