Module render 

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.

The main entry point to the rendering system is the implementation of FormatRenderer on Context.

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

use std::borrow::Cow; 🔒

use std::cmp::Ordering; 🔒

use std::collections::BTreeMap; 🔒

use std::collections::VecDeque; 🔒

use std::fmt; 🔒

use std::fmt::Display as _; 🔒

use std::fmt::Write; 🔒

use std::iter::Peekable; 🔒

use std::path::PathBuf; 🔒

use std::fs; 🔒

use std::str; 🔒

use askama::Template; 🔒

use askama::Template; 🔒

use indexmap::IndexMap; 🔒

use itertools::Either; 🔒

use rustc_ast::join_path_syms; 🔒

use rustc_attr_ir::AttributeKind; 🔒

use rustc_attr_ir::ConstStability; 🔒

use rustc_attr_ir::DeprecatedSince; 🔒

use rustc_attr_ir::Deprecation; 🔒

use rustc_attr_ir::NotableTraitColor; 🔒

use rustc_attr_ir::RustcVersion; 🔒

use rustc_attr_ir::StabilityLevel; 🔒

use rustc_attr_ir::StableSince; 🔒

use rustc_attr_ir::find_attr; 🔒

use rustc_data_structures::fx::FxHashSet; 🔒

use rustc_data_structures::fx::FxIndexMap; 🔒

use rustc_data_structures::fx::FxIndexSet; 🔒

use rustc_hir::Mutability; 🔒

use rustc_hir::def::DefKind; 🔒

use rustc_hir::def_id::DefId; 🔒

use rustc_hir::def_id::DefIdSet; 🔒

use rustc_middle::ty::print::PrintTraitRefExt; 🔒

use rustc_middle::ty; 🔒

use rustc_middle::ty::TyCtxt; 🔒

use rustc_span::DUMMY_SP; 🔒

use rustc_span::symbol::Symbol; 🔒

use rustc_span::symbol::sym; 🔒

use tracing::debug; 🔒

use tracing::info; 🔒

use crate::clean; 🔒

use crate::clean::Defaultness; 🔒

use crate::clean::Item; 🔒

use crate::clean::ItemId; 🔒

use crate::clean::ItemKind; 🔒

use crate::clean::RenderedLink; 🔒

use crate::display::Joined as _; 🔒

use crate::display::MaybeDisplay as _; 🔒

use crate::error::Error; 🔒

use crate::formats::Impl; 🔒

use crate::formats::cache::Cache; 🔒

use crate::formats::item_type::ItemType; 🔒

use crate::html::escape::Escape; 🔒

use crate::html::format::Ending; 🔒

use crate::html::format::HrefError; 🔒

use crate::html::format::HrefInfo; 🔒

use crate::html::format::PrintWithSpace; 🔒

use crate::html::format::full_print_fn_decl; 🔒

use crate::html::format::href; 🔒

use crate::html::format::print_abi_with_space; 🔒

use crate::html::format::print_constness_with_space; 🔒

use crate::html::format::print_generic_bounds; 🔒

use crate::html::format::print_generics; 🔒

use crate::html::format::print_impl; 🔒

use crate::html::format::print_path; 🔒

use crate::html::format::print_type; 🔒

use crate::html::format::print_where_clause; 🔒

use crate::html::format::visibility_print_with_space; 🔒

use crate::html::markdown::HeadingOffset; 🔒

use crate::html::markdown::IdMap; 🔒

use crate::html::markdown::Markdown; 🔒

use crate::html::markdown::MarkdownItemInfo; 🔒

use crate::html::markdown::MarkdownSummaryLine; 🔒

use crate::html::markdown::short_markdown_summary; 🔒

use crate::html::render::print_item::ImplString; 🔒

use crate::html::render::search_index::get_function_type_for_search; 🔒

use crate::html::static_files::SCRAPE_EXAMPLES_HELP_MD; 🔒

use crate::html::highlight; 🔒

use crate::html::sources; 🔒

use crate::scrape_examples::CallData; 🔒

use crate::scrape_examples::CallLocation; 🔒

use crate::DOC_RUST_LANG_ORG_VERSION; 🔒

use crate::try_none; 🔒

Modules

context 🔒

flock 🔒

ordered_json 🔒

print_item 🔒

search_index 🔒

sidebar 🔒

sorted_template 🔒

type_layout 🔒

write_shared 🔒

Rustdoc writes aut two kinds of shared files:

Structs

AliasSerializableImpl 🔒

Final serialized form of the alias impl

AliasedType 🔒

Data for an aliased type.

AliasedTypeImpl 🔒

The impl_ contains data that’s used to figure out if an alias will work, and to generate the HTML at the end.

AllCrates 🔒

AllCratesEntry 🔒

Type of a serialized entry in the AllCratesPart JSON.

AllTypes 🔒

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.

ContextInfo 🔒

This struct contains the information that needs to be reset between each FormatRenderer::item call.

CrateInfo 🔒

Contains pre-rendered contents to insert into the CCI template

CratesIndex 🔒

Hierarchy 🔒

Source files directory tree

ImplRenderingParameters 🔒

Implementor 🔒

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.

IndexItemInfo 🔒

ItemEntry 🔒

ItemInfo 🔒

NotableTraitBadge 🔒

Part 🔒

A piece of one of the shared artifacts for documentation (search index, sources, alias list, etc.)

PartsAndLocations 🔒

Paths (relative to the doc root) and their pre-merge contents

RenderType 🔒

A type used for the search index.

SharedContext 🔒

Shared mutable state used in Context and elsewhere.

SidebarItem 🔒

Sources 🔒

StylePath 🔒

TraitAlias 🔒

TypeAlias 🔒

TypeImplCollector 🔒

Collect the list of aliased types and their aliases. https://github.com/search?q=repo%3Arust-lang%2Frust+[RUSTDOCIMPL]+type.impl&type=code

Enums

AssocItemLink 🔒

AssocItemRender 🔒

Specifies whether rendering directly implemented trait items or ones from a certain Deref impl.

CrateInfoVersion 🔒

Version for the format of the crate-info file.

ItemSection 🔒

RenderMode 🔒

For different handling of associated items from the Deref target of a type rather than the type itself.

RenderTypeId 🔒

ShortItemInfo 🔒

Constants

MAX_FULL_EXAMPLES 🔒

NUM_VISIBLE_LINES 🔒

Traits

CciPart 🔒

Wrapper trait for Part<T, U>

Functions

assoc_const 🔒

assoc_fn 🔒

assoc_href_attr 🔒

Build a (possibly empty) href attribute (a key-value pair) for the given associated item.

assoc_ty 🔒

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

compute_if_deref_target_implements_copy 🔒

create_parents 🔒

Create all parents

document 🔒

document_full 🔒

document_full_collapsible 🔒

document_full_inner 🔒

document_item_info 🔒

Add extra information about an item such as:

document_short 🔒

Writes a documentation block containing only the first paragraph of the documentation. If the docs are longer, a “Read more” link is appended to the end.

ensure_trailing_slash 🔒

extract_for_impl_name 🔒

get_filtered_impls_for_reference 🔒

Returns the list of implementations for the primitive reference type, filtering out any implementations that are on concrete or partially generic types, only keeping implementations of the form impl<T> Trait for &T.

get_id_for_impl 🔒

get_path_parts 🔒

hack_get_external_crate_names 🔒

Reads crates.js, which seems like the best place to obtain the list of externally documented crates if the index page was disabled when documenting the deps.

impl_trait_key 🔒

is_notable_trait_passthrough 🔒

Box has pass-through impls for Read, Write, Iterator, and Future when the boxed type implements one of those. We don’t want to treat every Box return as being notably an Iterator (etc), though, so we exempt it. Pin has the same issue, with a pass-through impl for Future.

item_ty_to_section 🔒

notable_trait_badges 🔒

Returns all #[doc(notable_trait)] traits that item implements, to be rendered as badges at the top of the item’s page.

notable_traits_button 🔒

notable_traits_decl_for_item 🔒

notable_traits_decl_for_type 🔒

notable_traits_decl_write_html 🔒

notable_traits_json 🔒

portability 🔒

read_template_or_blank 🔒

Returns a blank template unless we could find one to append to

render_all_impls 🔒

render_assoc_item 🔒

render_assoc_items 🔒

render_assoc_items_inner 🔒

render_attributes_in_code 🔒

render_attributes_in_code_with_options 🔒

render_call_locations 🔒

Generates the HTML for example call locations generated via the –scrape-examples flag.

render_code_attribute 🔒

render_deref_methods 🔒

derefs is the set of all deref targets that have already been handled.

render_impl 🔒

render_impl_summary 🔒

render_impls 🔒

render_markdown 🔒

Render md_text as markdown.

render_repr_attribute_in_code 🔒

render_rightside 🔒

render_stability_since_raw 🔒

render_stability_since_raw_with_extra 🔒

Writes a span containing the versions at which an item became stable and/or const-stable. For example, if the item became stable at 1.0.0, and const-stable at 1.45.0, this function would write a span containing “1.0.0 (const: 1.45.0)”.

repr_attribute 🔒

Compute the public #[repr] of the item given by DefId.

scrape_examples_help 🔒

short_item_info 🔒

Render the stability, deprecation and portability information that is displayed at the top of the item’s documentation.

should_render_item_for_deref 🔒

since_to_string 🔒

small_url_encode 🔒

write_impl_section_heading 🔒

write_not_crate_specific 🔒

Writes files that are written directly to the --out-dir, without the prefix from the current crate. These are the rendered cross-crate files that encode info from multiple crates (e.g. search index), and the static files.

write_rendered_cci 🔒

info from this crate and the –include-info-json’d crates

write_rendered_cross_crate_info 🔒

write_resources 🔒

Writes the static files, the style files, and the css extensions. Have to be careful about these, because they write to the root out dir.

write_section_heading 🔒

write_shared 🔒

Type Aliases

AllCratesPart 🔒

CratesIndexPart 🔒

SourcesPart 🔒

TraitAliasPart 🔒

TypeAliasPart 🔒