rustdoc/html/
layout.rs

Help
1use std::fmt::{self, Display};
2use std::path::PathBuf;
3
4use rinja::Template;
5use rustc_data_structures::fx::FxIndexMap;
6
7use super::static_files::{STATIC_FILES, StaticFiles};
8use crate::externalfiles::ExternalHtml;
9use crate::html::render::{StylePath, ensure_trailing_slash};
10
11#[derive(Clone)]
12pub(crate) struct Layout {
13    pub(crate) logo: String,
14    pub(crate) favicon: String,
15    pub(crate) external_html: ExternalHtml,
16    pub(crate) default_settings: FxIndexMap<String, String>,
17    pub(crate) krate: String,
18    pub(crate) krate_version: String,
19    /// The given user css file which allow to customize the generated
20    /// documentation theme.
21    pub(crate) css_file_extension: Option<PathBuf>,
22    /// If true, then scrape-examples.js will be included in the output HTML file
23    pub(crate) scrape_examples_extension: bool,
24}
25
26pub(crate) struct Page<'a> {
27    pub(crate) title: &'a str,
28    pub(crate) css_class: &'a str,
29    pub(crate) root_path: &'a str,
30    pub(crate) static_root_path: Option<&'a str>,
31    pub(crate) description: &'a str,
32    pub(crate) resource_suffix: &'a str,
33    pub(crate) rust_logo: bool,
34}
35
36impl Page<'_> {
37    pub(crate) fn get_static_root_path(&self) -> String {
38        match self.static_root_path {
39            Some(s) => s.to_string(),
40            None => format!("{}static.files/", self.root_path),
41        }
42    }
43}
44
45#[derive(Template)]
46#[template(path = "page.html")]
47struct PageLayout<'a> {
48    static_root_path: String,
49    page: &'a Page<'a>,
50    layout: &'a Layout,
51
52    files: &'static StaticFiles,
53
54    themes: Vec<String>,
55    sidebar: String,
56    content: String,
57    rust_channel: &'static str,
58    pub(crate) rustdoc_version: &'a str,
59    // same as layout.krate, except on top-level pages like
60    // Settings, Help, All Crates, and About Scraped Examples,
61    // where these things instead give Rustdoc name and version.
62    //
63    // These are separate from the variables used for the search
64    // engine, because "Rustdoc" isn't necessarily a crate in
65    // the current workspace.
66    display_krate: &'a str,
67    display_krate_with_trailing_slash: String,
68    display_krate_version_number: &'a str,
69    display_krate_version_extra: &'a str,
70}
71
72pub(crate) use crate::html::render::sidebar::filters;
73
74/// Implements [`Display`] for a function that accepts a mutable reference to a [`String`], and (optionally) writes to it.
75///
76/// The wrapped function will receive an empty string, and can modify it,
77/// and the `Display` implementation will write the contents of the string after the function has finished.
78pub(crate) struct BufDisplay<F>(pub F);
79
80impl<F> Display for BufDisplay<F>
81where
82    F: Fn(&mut String),
83{
84    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
85        let mut buf = String::new();
86        self.0(&mut buf);
87        f.write_str(&buf)
88    }
89}
90
91pub(crate) fn render<T: Display, S: Display>(
92    layout: &Layout,
93    page: &Page<'_>,
94    sidebar: S,
95    t: T,
96    style_files: &[StylePath],
97) -> String {
98    let rustdoc_version = rustc_interface::util::version_str!().unwrap_or("unknown version");
99
100    let (display_krate, display_krate_version, display_krate_with_trailing_slash) =
101        if page.root_path == "./" {
102            // top level pages use Rust branding
103            ("Rustdoc", rustdoc_version, String::new())
104        } else {
105            let display_krate_with_trailing_slash =
106                ensure_trailing_slash(&layout.krate).to_string();
107            (&layout.krate[..], &layout.krate_version[..], display_krate_with_trailing_slash)
108        };
109    let static_root_path = page.get_static_root_path();
110
111    // bootstrap passes in parts of the version separated by tabs, but other stuff might use spaces
112    let (display_krate_version_number, display_krate_version_extra) =
113        display_krate_version.split_once([' ', '\t']).unwrap_or((display_krate_version, ""));
114
115    let mut themes: Vec<String> = style_files.iter().map(|s| s.basename().unwrap()).collect();
116    themes.sort();
117
118    let content = t.to_string(); // Note: This must happen before making the sidebar.
119    let sidebar = sidebar.to_string();
120    PageLayout {
121        static_root_path,
122        page,
123        layout,
124        files: &STATIC_FILES,
125        themes,
126        sidebar,
127        content,
128        display_krate,
129        display_krate_with_trailing_slash,
130        display_krate_version_number,
131        display_krate_version_extra,
132        rust_channel: *crate::clean::utils::RUSTDOC_VERSION,
133        rustdoc_version,
134    }
135    .render()
136    .unwrap()
137}
138
139pub(crate) fn redirect(url: &str) -> String {
140    // <script> triggers a redirect before refresh, so this is fine.
141    format!(
142        r##"<!DOCTYPE html>
143<html lang="en">
144<head>
145    <meta http-equiv="refresh" content="0;URL={url}">
146    <title>Redirection</title>
147</head>
148<body>
149    <p>Redirecting to <a href="{url}">{url}</a>...</p>
150    <script>location.replace("{url}" + location.search + location.hash);</script>
151</body>
152</html>"##,
153        url = url,
154    )
155}
rustdoc/html/layout.rs

rustdoc/html/
layout.rs
