Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Migrate rustdoc from Tera to Askama #92526

Merged
merged 3 commits into from
Jan 13, 2022
Merged

Migrate rustdoc from Tera to Askama #92526

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
93a16cb
Migrate rustdoc from Tera to Askama
djc Jan 3, 2022
b00d666
Address feedback
djc Jan 3, 2022
ef96d57
Remove configuration which became unused in 8abb4bb698c9d74507adb9cd7…
djc Jan 9, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 59 additions & 27 deletions Cargo.lock
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,47 @@ version = "0.7.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5a2f58b0bb10c380af2b26e57212856b8c9a59e0925b4c20f4a174a49734eaf7"

[[package]]
name = "askama"
version = "0.11.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4d8f355701c672c2ba3d718acbd213f740beea577cc4eae66accdffe15be1882"
dependencies = [
"askama_derive",
"askama_escape",
"askama_shared",
]

[[package]]
name = "askama_derive"
version = "0.11.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "84704cab5b7ae0fd3a9f78ee5eb7b27f3749df445f04623db6633459ae283267"
dependencies = [
"askama_shared",
"proc-macro2",
"syn",
]

[[package]]
name = "askama_escape"
version = "0.10.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9a1bb320f97e6edf9f756bf015900038e43c7700e059688e5724a928c8f3b8d5"

[[package]]
name = "askama_shared"
version = "0.12.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "dae03eebba55a2697a376e58b573a29fe36893157173ac8df312ad85f3c0e012"
dependencies = [
"askama_escape",
"nom",
"proc-macro2",
"quote",
"syn",
]

[[package]]
name = "atty"
version = "0.2.14"
Expand Down Expand Up @@ -1509,17 +1550,6 @@ dependencies = [
"regex",
]

[[package]]
name = "globwalk"
version = "0.8.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "93e3af942408868f6934a7b85134a3230832b9977cf66125df2f9edcfce4ddcc"
dependencies = [
"bitflags",
"ignore",
"walkdir",
]

[[package]]
name = "gsgdt"
version = "0.1.2"
Expand Down Expand Up @@ -2245,6 +2275,12 @@ dependencies = [
"macro-utils",
]

[[package]]
name = "minimal-lexical"
version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"

[[package]]
name = "miniz_oxide"
version = "0.4.0"
Expand Down Expand Up @@ -2304,6 +2340,17 @@ version = "1.0.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e4a24736216ec316047a1fc4252e27dabb04218aa4a3f37c6e7ddbf1f9782b54"

[[package]]
name = "nom"
version = "7.1.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1b1d11e1ef389c76fe5b81bcaf2ea32cf88b62bc494e19f493d0b30e7a930109"
dependencies = [
"memchr",
"minimal-lexical",
"version_check",
]

[[package]]
name = "ntapi"
version = "0.3.6"
Expand Down Expand Up @@ -4631,6 +4678,7 @@ name = "rustdoc"
version = "0.0.0"
dependencies = [
"arrayvec",
"askama",
"expect-test",
"itertools 0.9.0",
"minifier",
Expand All @@ -4642,7 +4690,6 @@ dependencies = [
"serde_json",
"smallvec",
"tempfile",
"tera",
"tracing",
"tracing-subscriber",
"tracing-tree",
Expand Down Expand Up @@ -5187,21 +5234,6 @@ dependencies = [
"utf-8",
]

[[package]]
name = "tera"
version = "1.10.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "81060acb882480c8793782eb96bc86f5c83d2fc7175ad46c375c6956ef7afa62"
dependencies = [
"globwalk",
"lazy_static",
"pest",
"pest_derive",
"regex",
"serde",
"serde_json",
]

[[package]]
name = "term"
version = "0.6.1"
Expand Down
2 changes: 1 addition & 1 deletion src/librustdoc/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ path = "lib.rs"

[dependencies]
arrayvec = { version = "0.7", default-features = false }
askama = { version = "0.11", default-features = false }
pulldown-cmark = { version = "0.9", default-features = false }
minifier = "0.0.41"
rayon = "1.3.1"
Expand All @@ -20,7 +21,6 @@ regex = "1"
rustdoc-json-types = { path = "../rustdoc-json-types" }
tracing = "0.1"
tracing-tree = "0.2.0"
tera = { version = "1.10.0", default-features = false }

[dependencies.tracing-subscriber]
version = "0.3.3"
Expand Down
5 changes: 0 additions & 5 deletions src/librustdoc/config.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -257,9 +257,6 @@ crate struct RenderOptions {
/// If present, playground URL to use in the "Run" button added to code samples generated from
/// standalone Markdown files. If not present, `playground_url` is used.
crate markdown_playground_url: Option<String>,
/// If false, the `select` element to have search filtering by crates on rendered docs
/// won't be generated.
crate generate_search_filter: bool,
/// Document items that have lower than `pub` visibility.
crate document_private: bool,
/// Document items that have `doc(hidden)`.
Expand Down Expand Up @@ -638,7 +635,6 @@ impl Options {
let crate_version = matches.opt_str("crate-version");
let enable_index_page = matches.opt_present("enable-index-page") || index_page.is_some();
let static_root_path = matches.opt_str("static-root-path");
let generate_search_filter = !matches.opt_present("disable-per-crate-search");
let test_run_directory = matches.opt_str("test-run-directory").map(PathBuf::from);
let persist_doctests = matches.opt_str("persist-doctests").map(PathBuf::from);
let test_builder = matches.opt_str("test-builder").map(PathBuf::from);
Expand Down Expand Up @@ -724,7 +720,6 @@ impl Options {
markdown_no_toc,
markdown_css,
markdown_playground_url,
generate_search_filter,
document_private,
document_hidden,
generate_redirect_map,
Expand Down
20 changes: 8 additions & 12 deletions src/librustdoc/html/layout.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,9 @@ use crate::externalfiles::ExternalHtml;
use crate::html::format::{Buffer, Print};
use crate::html::render::{ensure_trailing_slash, StylePath};

use serde::Serialize;
use askama::Template;

#[derive(Clone, Serialize)]
#[derive(Clone)]
crate struct Layout {
crate logo: String,
crate favicon: String,
Expand All @@ -19,14 +19,10 @@ crate struct Layout {
/// The given user css file which allow to customize the generated
/// documentation theme.
crate css_file_extension: Option<PathBuf>,
/// If false, the `select` element to have search filtering by crates on rendered docs
/// won't be generated.
crate generate_search_filter: bool,
/// If true, then scrape-examples.js will be included in the output HTML file
crate scrape_examples_extension: bool,
}

#[derive(Serialize)]
crate struct Page<'a> {
crate title: &'a str,
crate css_class: &'a str,
Expand All @@ -45,7 +41,8 @@ impl<'a> Page<'a> {
}
}

#[derive(Serialize)]
#[derive(Template)]
#[template(path = "page.html")]
struct PageLayout<'a> {
static_root_path: &'a str,
page: &'a Page<'a>,
Expand All @@ -58,7 +55,6 @@ struct PageLayout<'a> {
}

crate fn render<T: Print, S: Print>(
templates: &tera::Tera,
layout: &Layout,
page: &Page<'_>,
sidebar: S,
Expand All @@ -76,7 +72,7 @@ crate fn render<T: Print, S: Print>(
let rustdoc_version = rustc_interface::util::version_str().unwrap_or("unknown version");
let content = Buffer::html().to_display(t); // Note: This must happen before making the sidebar.
let sidebar = Buffer::html().to_display(sidebar);
let teractx = tera::Context::from_serialize(PageLayout {
PageLayout {
static_root_path,
page,
layout,
Expand All @@ -85,9 +81,9 @@ crate fn render<T: Print, S: Print>(
content,
krate_with_trailing_slash,
rustdoc_version,
})
.unwrap();
templates.render("page.html", &teractx).unwrap()
}
.render()
.unwrap()
}

crate fn redirect(url: &str) -> String {
Expand Down
12 changes: 1 addition & 11 deletions src/librustdoc/html/render/context.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,6 @@ use rustc_span::symbol::sym;

use super::print_item::{full_path, item_path, print_item};
use super::search_index::build_index;
use super::templates;
use super::write_shared::write_shared;
use super::{
collect_spans_and_sources, print_sidebar, settings, AllTypes, LinkFromSrc, NameDoc, StylePath,
Expand Down Expand Up @@ -118,8 +117,6 @@ crate struct SharedContext<'tcx> {
/// the crate.
redirections: Option<RefCell<FxHashMap<String, String>>>,

pub(crate) templates: tera::Tera,

/// Correspondance map used to link types used in the source code pages to allow to click on
/// links to jump to the type's definition.
crate span_correspondance_map: FxHashMap<rustc_span::Span, LinkFromSrc>,
Expand Down Expand Up @@ -218,11 +215,10 @@ impl<'tcx> Context<'tcx> {

if !self.render_redirect_pages {
layout::render(
&self.shared.templates,
&self.shared.layout,
&page,
|buf: &mut _| print_sidebar(self, it, buf),
|buf: &mut _| print_item(self, &self.shared.templates, it, buf, &page),
|buf: &mut _| print_item(self, it, buf, &page),
&self.shared.style_files,
)
} else {
Expand Down Expand Up @@ -391,7 +387,6 @@ impl<'tcx> FormatRenderer<'tcx> for Context<'tcx> {
extension_css,
resource_suffix,
static_root_path,
generate_search_filter,
unstable_features,
generate_redirect_map,
show_type_layout,
Expand Down Expand Up @@ -421,12 +416,10 @@ impl<'tcx> FormatRenderer<'tcx> for Context<'tcx> {
default_settings,
krate: krate.name(tcx).to_string(),
css_file_extension: extension_css,
generate_search_filter,
scrape_examples_extension: !call_locations.is_empty(),
};
let mut issue_tracker_base_url = None;
let mut include_sources = true;
let templates = templates::load()?;

// Crawl the crate attributes looking for attributes which control how we're
// going to emit HTML
Expand Down Expand Up @@ -481,7 +474,6 @@ impl<'tcx> FormatRenderer<'tcx> for Context<'tcx> {
errors: receiver,
redirections: if generate_redirect_map { Some(Default::default()) } else { None },
show_type_layout,
templates,
span_correspondance_map: matches,
cache,
call_locations,
Expand Down Expand Up @@ -577,7 +569,6 @@ impl<'tcx> FormatRenderer<'tcx> for Context<'tcx> {
};
let all = self.shared.all.replace(AllTypes::new());
let v = layout::render(
&self.shared.templates,
&self.shared.layout,
&page,
sidebar,
Expand All @@ -599,7 +590,6 @@ impl<'tcx> FormatRenderer<'tcx> for Context<'tcx> {
.map(StylePath::basename)
.collect::<Result<_, Error>>()?;
let v = layout::render(
&self.shared.templates,
&self.shared.layout,
&page,
sidebar,
Expand Down
1 change: 0 additions & 1 deletion src/librustdoc/html/render/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,6 @@ mod tests;
mod context;
mod print_item;
mod span_map;
mod templates;
mod write_shared;

crate use self::context::*;
Expand Down
17 changes: 5 additions & 12 deletions src/librustdoc/html/render/print_item.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,21 +32,21 @@ use crate::html::highlight;
use crate::html::layout::Page;
use crate::html::markdown::{HeadingOffset, MarkdownSummaryLine};

use serde::Serialize;
use askama::Template;

const ITEM_TABLE_OPEN: &str = "<div class=\"item-table\">";
const ITEM_TABLE_CLOSE: &str = "</div>";
const ITEM_TABLE_ROW_OPEN: &str = "<div class=\"item-row\">";
const ITEM_TABLE_ROW_CLOSE: &str = "</div>";

// A component in a `use` path, like `string` in std::string::ToString
#[derive(Serialize)]
struct PathComponent<'a> {
path: String,
name: &'a str,
}

#[derive(Serialize)]
#[derive(Template)]
#[template(path = "print_item.html")]
struct ItemVars<'a> {
page: &'a Page<'a>,
static_root_path: &'a str,
Expand All @@ -58,13 +58,7 @@ struct ItemVars<'a> {
src_href: Option<&'a str>,
}

pub(super) fn print_item(
cx: &Context<'_>,
templates: &tera::Tera,
item: &clean::Item,
buf: &mut Buffer,
page: &Page<'_>,
) {
pub(super) fn print_item(cx: &Context<'_>, item: &clean::Item, buf: &mut Buffer, page: &Page<'_>) {
debug_assert!(!item.is_stripped());
let typ = match *item.kind {
clean::ModuleItem(_) => {
Expand Down Expand Up @@ -143,8 +137,7 @@ pub(super) fn print_item(
src_href: src_href.as_deref(),
};

let teractx = tera::Context::from_serialize(item_vars).unwrap();
let heading = templates.render("print_item.html", &teractx).unwrap();
let heading = item_vars.render().unwrap();
Copy link
Contributor Author

@djc djc Jan 3, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A further performance improvement here would be to make sure that Buffer impls core::fmt::Write, in which case we could use render_into(buf) rather than render(), avoiding the allocation of a temporary String here. Buffer internally seems to just hold a String and it has write_str() and write_fmt() methods already, so perhaps it would make sense to implement that trait? I'm not sure how big/relevant the performance improvement would be.

buf.write_str(&heading);

match *item.kind {
Expand Down
20 changes: 0 additions & 20 deletions src/librustdoc/html/render/templates.rs
View file
Open in desktop

This file was deleted.

Loading