Module rustdoc::html::render[][src]

Rustdoc's HTML Rendering module

This modules contains the bulk of the logic necessary for rendering a rustdoc clean::Crate instance to a set of static HTML pages. This rendering process is largely driven by the format! syntax extension to perform all I/O into files and streams.

The rendering process is largely driven by the Context and Cache structures. The cache is pre-populated by crawling the crate in question, and then it is shared among the various rendering threads. The cache is meant to be a fairly large structure not implementing Clone (because it's shared among threads). The context, however, should be a lightweight structure. This is cloned per-thread and contains information about what is currently being rendered.

In order to speed up rendering (mostly because of markdown rendering), the rendering process has been parallelized. This parallelization is only exposed through the crate method on the context, and then also from the fact that the shared cache is stored in TLS (and must be accessed as such).

In addition to rendering the crate itself, this module is also responsible for creating the corresponding search index and source file renderings. These threads are not parallelized (they haven't been a bottleneck yet), and both occur before the crate is rendered.

Re-exports

pub use self::ExternalLocation::*;
use std::borrow::Cow;
use std::cell::RefCell;
use std::cmp::Ordering;
use std::collections::BTreeMap;
use std::collections::HashSet;
use std::collections::VecDeque;
use std::default::Default;
use std::error;
use std::fmt;
use std::fmt::Display;
use std::fmt::Formatter;
use std::fmt::Write as FmtWrite;
use std::fs;
use std::fs::File;
use std::fs::OpenOptions;
use std::io::prelude::*;
use std::io;
use std::io::BufWriter;
use std::io::BufReader;
use std::iter::repeat;
use std::mem;
use std::path::PathBuf;
use std::path::Path;
use std::path::Component;
use std::str;
use std::sync::Arc;
use externalfiles::ExternalHtml;
use serialize::json::ToJson;
use serialize::json::Json;
use serialize::json::as_json;
use syntax::ast;
use syntax::codemap::FileName;
use rustc::hir::def_id::CrateNum;
use rustc::hir::def_id::CRATE_DEF_INDEX;
use rustc::hir::def_id::DefId;
use rustc::middle::privacy::AccessLevels;
use rustc::middle::stability;
use rustc::hir;
use rustc::util::nodemap::FxHashMap;
use rustc::util::nodemap::FxHashMap;
use rustc::util::nodemap::FxHashSet;
use rustc::util::nodemap::FxHashSet;
use rustc_data_structures::flock;
use rustc_target::spec::abi;
use clean;
use clean::AttributesExt;
use clean::GetDefId;
use clean::SelfTy;
use clean::Mutability;
use doctree;
use fold::DocFolder;
use html::escape::Escape;
use html::format::ConstnessSpace;
use html::format::TyParamBounds;
use html::format::WhereClause;
use html::format::href;
use html::format::AbiSpace;
use html::format::VisSpace;
use html::format::Method;
use html::format::UnsafetySpace;
use html::format::MutableSpace;
use html::format::fmt_impl_for_trait_page;
use html::item_type::ItemType;
use html::markdown;
use html::markdown::Markdown;
use html::markdown::MarkdownHtml;
use html::markdown::MarkdownSummaryLine;
use html::highlight;
use html::layout;
use minifier;

Structs

AllTypes
Cache

This cache is used to store information about the clean::Crate being rendered in order to provide more useful documentation. This contains information like all implementors of a trait, all traits a type implements, documentation for all known traits, etc.

Context

Major driving force in all rustdoc rendering. This contains information about where in the tree-like hierarchy rendering is occurring and controls how the current page is being rendered.

Error
Impl

Metadata about implementations for a type or trait.

IndexItem

Struct representing one entry in the JS search index. These are all emitted by hand to a large JS file at the end of cache-creation.

IndexItemFunctionType

Full type of functions/methods in the search index.

Initializer
Item
ItemEntry
RenderInfo

Temporary storage for data obtained during RustdocVisitor::clean(). Later on moved into CACHE_KEY.

Settings
SharedContext
Sidebar
Source

Wrapper struct to render the source code of a file. This will do things like adding line numbers to the left-hand side.

SourceCollector

Helper struct to render all source code to HTML pages

Type

A type used for the search index.

Enums

AssocItemLink
AssocItemRender
ExternalLocation

Indicates where an external crate can be found.

RenderMode

Constants

ATTRIBUTE_WHITELIST
BASIC_KEYWORDS
CACHE_KEY
CURRENT_LOCATION_KEY
USED_ID_MAP

Functions

assoc_const
assoc_type
build_index

Build the search index from the collected metadata

cache
clean_srcpath

Takes a path to a source file and cleans the path to it. This canonicalizes things like ".." to components which preserve the "top down" hierarchy of a static HTML tree. Each component in the cleaned path will be passed as an argument to f. The very last component of the path (ie the file name) will be passed to f if keep_filename is true, and ignored otherwise.

collect_paths_for_type

Returns a list of all paths used in the type. This is used to help deduplicate imported impls for reexported types. If any of the contained types are re-exported, we don't use the corresponding entry from the js file, as inlining will have already picked up the impl

derive_id
document
document_full
document_short
document_stability
extern_location

Attempts to find where an external crate is located, given that we're rendering in to the specified source destination.

extract_for_impl_name
full_path
get_generics
get_index_search_type
get_index_type
get_index_type_name
get_methods
get_struct_fields_name
init_ids
is_negative_impl
item_constant
item_enum
item_foreign_type
item_function
item_keyword
item_macro
item_module
item_path
item_primitive
item_static
item_struct
item_trait
item_ty_to_strs
item_typedef
item_union
make_item_keywords
naive_assoc_href
name_key
plain_summary_line
print_entries
render_assoc_const_value
render_assoc_item
render_assoc_items
render_attribute
render_attributes
render_deref_methods
render_impl
render_implementor
render_impls
render_markdown

Render md_text as markdown.

render_sources
render_spotlight_traits
render_stability_since
render_stability_since_raw
render_struct
render_union
reset_ids

This method resets the local table of used ID attributes. This is typically used at the beginning of rendering an entire HTML page to reset from the previous state (if any).

run

Generates the documentation for crate into the directory dst

short_stability
shorter
should_render_item
sidebar_assoc_items
sidebar_enum
sidebar_foreign_type
sidebar_module
sidebar_primitive
sidebar_struct
sidebar_trait
sidebar_typedef
sidebar_union
small_url_encode
spotlight_decl
wrap_into_docblock
write

Writes the entire contents of a string to a destination, not attempting to catch any errors.

write_minify
write_shared

Type Definitions

NameDoc

A pair of name and its optional document.