rust/src/librustdoc/html/layout.rs

use std::path::PathBuf;

use rustc_data_structures::fx::FxHashMap;

use crate::externalfiles::ExternalHtml;
use crate::html::escape::Escape;
use crate::html::format::{Buffer, Print};
use crate::html::render::{ensure_trailing_slash, StylePath};

#[derive(Clone)]
crate struct Layout {
    crate logo: String,
    crate favicon: String,
    crate external_html: ExternalHtml,
    crate default_settings: FxHashMap<String, String>,
    crate krate: String,
    /// 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,
}

crate struct Page<'a> {
    crate title: &'a str,
    crate css_class: &'a str,
    crate root_path: &'a str,
    crate static_root_path: Option<&'a str>,
    crate description: &'a str,
    crate keywords: &'a str,
    crate resource_suffix: &'a str,
    crate extra_scripts: &'a [&'a str],
    crate static_extra_scripts: &'a [&'a str],
}

crate fn render<T: Print, S: Print>(
    layout: &Layout,
    page: &Page<'_>,
    sidebar: S,
    t: T,
    style_files: &[StylePath],
) -> String {
    let static_root_path = page.static_root_path.unwrap_or(page.root_path);
    format!(
        "<!DOCTYPE html>\
<html lang=\"en\">\
<head>\
    <meta charset=\"utf-8\">\
    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\
    <meta name=\"generator\" content=\"rustdoc\">\
    <meta name=\"description\" content=\"{description}\">\
    <meta name=\"keywords\" content=\"{keywords}\">\
    <title>{title}</title>\
    <link rel=\"stylesheet\" type=\"text/css\" href=\"{static_root_path}normalize{suffix}.css\">\
    <link rel=\"stylesheet\" type=\"text/css\" href=\"{static_root_path}rustdoc{suffix}.css\" \
          id=\"mainThemeStyle\">\
    {style_files}\
    <script id=\"default-settings\"{default_settings}></script>\
    <script src=\"{static_root_path}storage{suffix}.js\"></script>\
    <script src=\"{root_path}crates{suffix}.js\"></script>\
    <noscript><link rel=\"stylesheet\" href=\"{static_root_path}noscript{suffix}.css\"></noscript>\
    {css_extension}\
    {favicon}\
    {in_header}\
    <style type=\"text/css\">\
    #crate-search{{background-image:url(\"{static_root_path}down-arrow{suffix}.svg\");}}\
    </style>\
</head>\
<body class=\"rustdoc {css_class}\">\
    <!--[if lte IE 11]>\
    <div class=\"warning\">\
        This old browser is unsupported and will most likely display funky \
        things.\
    </div>\
    <![endif]-->\
    {before_content}\
    <nav class=\"sidebar\">\
        <div class=\"sidebar-menu\" role=\"button\">&#9776;</div>\
        {logo}\
        {sidebar}\
    </nav>\
    <div class=\"theme-picker\">\
        <button id=\"theme-picker\" aria-label=\"Pick another theme!\" aria-haspopup=\"menu\">\
            <img src=\"{static_root_path}brush{suffix}.svg\" \
                 width=\"18\" height=\"18\" \
                 alt=\"Pick another theme!\">\
        </button>\
        <div id=\"theme-choices\" role=\"menu\"></div>\
    </div>\
    <nav class=\"sub\">\
        <form class=\"search-form\">\
            <div class=\"search-container\">\
                <div>{filter_crates}\
                    <input class=\"search-input\" name=\"search\" \
                           disabled \
                           autocomplete=\"off\" \
                           spellcheck=\"false\" \
                           placeholder=\"Click or press ‘S’ to search, ‘?’ for more options…\" \
                           type=\"search\">\
                </div>\
                <button type=\"button\" class=\"help-button\">?</button>
                <a id=\"settings-menu\" href=\"{root_path}settings.html\">\
                    <img src=\"{static_root_path}wheel{suffix}.svg\" \
                         width=\"18\" height=\"18\" \
                         alt=\"Change settings\">\
                </a>\
            </div>\
        </form>\
    </nav>\
    <section id=\"main\" class=\"content\">{content}</section>\
    <section id=\"search\" class=\"content hidden\"></section>\
    {after_content}\
    <div id=\"rustdoc-vars\" data-root-path=\"{root_path}\" data-current-crate=\"{krate}\" \
       data-search-index-js=\"{root_path}search-index{suffix}.js\" \
       data-search-js=\"{static_root_path}search{suffix}.js\"></div>
    <script src=\"{static_root_path}main{suffix}.js\"></script>\
    {extra_scripts}\
</body>\
</html>",
        css_extension = if layout.css_file_extension.is_some() {
            format!(
                "<link rel=\"stylesheet\" \
                       type=\"text/css\" \
                       href=\"{static_root_path}theme{suffix}.css\">",
                static_root_path = static_root_path,
                suffix = page.resource_suffix
            )
        } else {
            String::new()
        },
        content = Buffer::html().to_display(t),
        static_root_path = static_root_path,
        root_path = page.root_path,
        css_class = page.css_class,
        logo = {
            if layout.logo.is_empty() {
                format!(
                    "<a href='{root}{path}index.html'>\
                     <div class='logo-container rust-logo'>\
                     <img src='{static_root_path}rust-logo{suffix}.png' alt='logo'></div></a>",
                    root = page.root_path,
                    path = ensure_trailing_slash(&layout.krate),
                    static_root_path = static_root_path,
                    suffix = page.resource_suffix
                )
            } else {
                format!(
                    "<a href='{root}{path}index.html'>\
                     <div class='logo-container'><img src='{logo}' alt='logo'></div></a>",
                    root = page.root_path,
                    path = ensure_trailing_slash(&layout.krate),
                    logo = layout.logo
                )
            }
        },
        title = page.title,
        description = page.description,
        keywords = page.keywords,
        favicon = if layout.favicon.is_empty() {
            format!(
                r##"<link rel="icon" type="image/svg+xml" href="{static_root_path}favicon{suffix}.svg">
<link rel="alternate icon" type="image/png" href="{static_root_path}favicon-16x16{suffix}.png">
<link rel="alternate icon" type="image/png" href="{static_root_path}favicon-32x32{suffix}.png">"##,
                static_root_path = static_root_path,
                suffix = page.resource_suffix
            )
        } else {
            format!(r#"<link rel="shortcut icon" href="{}">"#, layout.favicon)
        },
        in_header = layout.external_html.in_header,
        before_content = layout.external_html.before_content,
        after_content = layout.external_html.after_content,
        sidebar = Buffer::html().to_display(sidebar),
        krate = layout.krate,
        default_settings = layout
            .default_settings
            .iter()
            .map(|(k, v)| format!(r#" data-{}="{}""#, k.replace('-', "_"), Escape(v)))
            .collect::<String>(),
        style_files = style_files
            .iter()
            .filter_map(|t| {
                if let Some(stem) = t.path.file_stem() { Some((stem, t.disabled)) } else { None }
            })
            .filter_map(|t| {
                if let Some(path) = t.0.to_str() { Some((path, t.1)) } else { None }
            })
            .map(|t| format!(
                r#"<link rel="stylesheet" type="text/css" href="{}.css" {} {}>"#,
                Escape(&format!("{}{}{}", static_root_path, t.0, page.resource_suffix)),
                if t.1 { "disabled" } else { "" },
                if t.0 == "light" { "id=\"themeStyle\"" } else { "" }
            ))
            .collect::<String>(),
        suffix = page.resource_suffix,
        extra_scripts = page
            .static_extra_scripts
            .iter()
            .map(|e| {
                format!(
                    "<script src=\"{static_root_path}{extra_script}.js\"></script>",
                    static_root_path = static_root_path,
                    extra_script = e
                )
            })
            .chain(page.extra_scripts.iter().map(|e| {
                format!(
                    "<script src=\"{root_path}{extra_script}.js\"></script>",
                    root_path = page.root_path,
                    extra_script = e
                )
            }))
            .collect::<String>(),
        filter_crates = if layout.generate_search_filter {
            "<select id=\"crate-search\">\
                 <option value=\"All crates\">All crates</option>\
             </select>"
        } else {
            ""
        },
    )
}

crate fn redirect(url: &str) -> String {
    // <script> triggers a redirect before refresh, so this is fine.
    format!(
        r##"<!DOCTYPE html>
<html lang="en">
<head>
    <meta http-equiv="refresh" content="0;URL={url}">
</head>
<body>
    <p>Redirecting to <a href="{url}">{url}</a>...</p>
    <script>location.replace("{url}" + location.search + location.hash);</script>
</body>
</html>"##,
        url = url,
    )
}
-												Fasten even more theme switch

											
										
										
											2018-01-23 00:45:34 +01:00
+								use std::path::PathBuf;
-												Implement a web backend for rustdoc_ng

This large commit implements and `html` output option for rustdoc_ng. The
executable has been altered to be invoked as "rustdoc_ng html <crate>" and
it will dump everything into the local "doc" directory. JSON can still be
generated by changing 'html' to 'json'.

This also fixes a number of bugs in rustdoc_ng relating to comment stripping,
along with some other various issues that I found along the way.

The `make doc` command has been altered to generate the new documentation into
the `doc/ng/$(CRATE)` directories.

											
										
										
											2013-09-18 22:18:38 -07:00
-												Fix rustc::internal lints on rustdoc

											
										
										
											2020-12-31 23:25:30 -05:00
+								use rustc_data_structures::fx::FxHashMap;
-												Transition librustdoc to 2018 edition

											
										
										
											2019-02-23 16:40:07 +09:00
+								use crate::externalfiles::ExternalHtml;
-												Apply review comments

											
										
										
											2019-10-10 12:09:01 +02:00
+								use crate::html::escape::Escape;
-												Move sidebar to Buffer-printing

											
										
										
											2019-08-31 09:07:29 -04:00
+								use crate::html::format::{Buffer, Print};
-												Clean up handling of style files in rustdoc
Disable all themes other than `light.css` to prevent rule conflicts

											
										
										
											2020-07-12 14:37:22 -04:00
+								use crate::html::render::{ensure_trailing_slash, StylePath};
-												Fix image link in the settings menu

											
										
										
											2019-01-31 15:42:45 +01:00
-												sed -i -s 's/#\[deriving(/#\[derive(/g' **/*.rs

											
										
										
											2015-01-03 22:54:18 -05:00
+								#[derive(Clone)]
-												Make all rustdoc functions and structs crate-private

This gives warnings about dead code.

											
										
										
											2020-11-14 17:59:58 -05:00
+								crate struct Layout {
 								    crate logo: String,
 								    crate favicon: String,
 								    crate external_html: ExternalHtml,
-												Fix rustc::internal lints on rustdoc

											
										
										
											2020-12-31 23:25:30 -05:00
+								    crate default_settings: FxHashMap<String, String>,
-												Make all rustdoc functions and structs crate-private

This gives warnings about dead code.

											
										
										
											2020-11-14 17:59:58 -05:00
+								    crate krate: String,
-												Move constant parameters to render to Layout struct

											
										
										
											2019-08-30 10:51:13 -04:00
+								    /// The given user css file which allow to customize the generated
 								    /// documentation theme.
-												Make all rustdoc functions and structs crate-private

This gives warnings about dead code.

											
										
										
											2020-11-14 17:59:58 -05:00
+								    crate css_file_extension: Option<PathBuf>,
-												Move constant parameters to render to Layout struct

											
										
										
											2019-08-30 10:51:13 -04:00
+								    /// If false, the `select` element to have search filtering by crates on rendered docs
 								    /// won't be generated.
-												Make all rustdoc functions and structs crate-private

This gives warnings about dead code.

											
										
										
											2020-11-14 17:59:58 -05:00
+								    crate generate_search_filter: bool,
-												Implement a web backend for rustdoc_ng

This large commit implements and `html` output option for rustdoc_ng. The
executable has been altered to be invoked as "rustdoc_ng html <crate>" and
it will dump everything into the local "doc" directory. JSON can still be
generated by changing 'html' to 'json'.

This also fixes a number of bugs in rustdoc_ng relating to comment stripping,
along with some other various issues that I found along the way.

The `make doc` command has been altered to generate the new documentation into
the `doc/ng/$(CRATE)` directories.

											
										
										
											2013-09-18 22:18:38 -07:00
+								}
-												Make all rustdoc functions and structs crate-private

This gives warnings about dead code.

											
										
										
											2020-11-14 17:59:58 -05:00
+								crate struct Page<'a> {
 								    crate title: &'a str,
 								    crate css_class: &'a str,
 								    crate root_path: &'a str,
 								    crate static_root_path: Option<&'a str>,
 								    crate description: &'a str,
 								    crate keywords: &'a str,
 								    crate resource_suffix: &'a str,
 								    crate extra_scripts: &'a [&'a str],
 								    crate static_extra_scripts: &'a [&'a str],
-												Implement a web backend for rustdoc_ng

This large commit implements and `html` output option for rustdoc_ng. The
executable has been altered to be invoked as "rustdoc_ng html <crate>" and
it will dump everything into the local "doc" directory. JSON can still be
generated by changing 'html' to 'json'.

This also fixes a number of bugs in rustdoc_ng relating to comment stripping,
along with some other various issues that I found along the way.

The `make doc` command has been altered to generate the new documentation into
the `doc/ng/$(CRATE)` directories.

											
										
										
											2013-09-18 22:18:38 -07:00
+								}
-												Make all rustdoc functions and structs crate-private

This gives warnings about dead code.

											
										
										
											2020-11-14 17:59:58 -05:00
+								crate fn render<T: Print, S: Print>(
-												Add no-crate filter option on rustdoc

											
										
										
											2018-12-20 13:28:55 +01:00
+								    layout: &Layout,
-												Transition librustdoc to 2018 edition

											
										
										
											2019-02-23 16:40:07 +09:00
+								    page: &Page<'_>,
-												Implement Print for FnOnce(&mut Buffer)

This means that callers can pass in a closure like
`|buf| some_function(..., &mut buf)` and pass in arbitrary arguments to
that function without complicating the trait definition. We also keep
the impl for str and String, since it's useful to be able to just pass
in "" or format!("{}"...) results in some cases.

This changes Print's definition to take self, instead of &self, because
otherwise FnOnce cannot be called directly. We could instead take FnMut
or even Fn, but that seems like it'd merely complicate matters -- most
of the time, the FnOnce does not constrain us at all anyway. If it does,
a custom Print impl for &'_ SomeStruct is not all that painful.

											
										
										
											2019-08-31 11:22:51 -04:00
+								    sidebar: S,
-												layout::render takes Print instead of fmt::Display

											
										
										
											2019-08-31 12:18:25 -04:00
+								    t: T,
-												Clean up handling of style files in rustdoc
Disable all themes other than `light.css` to prevent rule conflicts

											
										
										
											2020-07-12 14:37:22 -04:00
+								    style_files: &[StylePath],
-												Create buffers in top-level rendering

This avoids needlessly creating and threading the buffers through when
we only use them once.

											
										
										
											2019-08-30 10:35:14 -04:00
+								) -> String {
-												new --static-root-path flag for controlling static file locations

											
										
										
											2018-12-20 10:18:45 -06:00
+								    let static_root_path = page.static_root_path.unwrap_or(page.root_path);
-												Format the world

											
										
										
											2019-12-22 17:42:04 -05:00
+								    format!(
 								        "<!DOCTYPE html>\
-												Small size reduction

											
										
										
											2018-04-14 17:13:46 +02:00
+								<html lang=\"en\">\
 								<head>\
 								    <meta charset=\"utf-8\">\
 								    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\
 								    <meta name=\"generator\" content=\"rustdoc\">\
 								    <meta name=\"description\" content=\"{description}\">\
 								    <meta name=\"keywords\" content=\"{keywords}\">\
 								    <title>{title}</title>\
-												new --static-root-path flag for controlling static file locations

											
										
										
											2018-12-20 10:18:45 -06:00
+								    <link rel=\"stylesheet\" type=\"text/css\" href=\"{static_root_path}normalize{suffix}.css\">\
 								    <link rel=\"stylesheet\" type=\"text/css\" href=\"{static_root_path}rustdoc{suffix}.css\" \
-												Small size reduction

											
										
										
											2018-04-14 17:13:46 +02:00
+								          id=\"mainThemeStyle\">\
-												Clean up handling of style files in rustdoc
Disable all themes other than `light.css` to prevent rule conflicts

											
										
										
											2020-07-12 14:37:22 -04:00
+								    {style_files}\
-												rustdoc: Provide a way to set the default settings from Rust code

rustdoc has various user-configurable preferences.  These are recorded
in web Local Storage (where available).  But we want to provide a way
to configure the default default, including for when web storage is
not available.

getSettingValue is the function responsible for looking up these
settings.  Here we make it fall back some in-DOM data, which
ultimately comes from RenderOptions.default_settings.

Using HTML data atrtributes is fairly convenient here, dsspite the
need to transform between snake and kebab case to avoid the DOM
converting kebab case to camel case (!)

We cache the element and dataset lookup in a global variable, to
ensure that getSettingValue remains fast.

The DOM representation has to be in an element which precedes the
inclusion of storage.js.  That means it has to be in the <head> and we
should not use an empty <div> as the container (although most browsers
will accept that).  An empty <script> element provides a convenient
and harmless container object.  <meta> would be another possibility
but runs a greater risk of having unwanted behaviours on weird
browsers.

We trust the RenderOptions not to contain unhelpful setting names,
which don't fit nicely into an HTML attribute.  It's awkward to quote
dataset keys.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

											
										
										
											2020-09-23 22:44:54 +01:00
+								    <script id=\"default-settings\"{default_settings}></script>\
-												new --static-root-path flag for controlling static file locations

											
										
										
											2018-12-20 10:18:45 -06:00
+								    <script src=\"{static_root_path}storage{suffix}.js\"></script>\
-												crates.js should use root_path and not static_root_path

											
										
										
											2021-03-13 21:21:03 +01:00
+								    <script src=\"{root_path}crates{suffix}.js\"></script>\
-												new --static-root-path flag for controlling static file locations

											
										
										
											2018-12-20 10:18:45 -06:00
+								    <noscript><link rel=\"stylesheet\" href=\"{static_root_path}noscript{suffix}.css\"></noscript>\
-												Small size reduction

											
										
										
											2018-04-14 17:13:46 +02:00
+								    {css_extension}\
 								    {favicon}\
 								    {in_header}\
-												Add arrow to the crate select box

											
										
										
											2018-11-29 01:29:49 +01:00
+								    <style type=\"text/css\">\
-												new --static-root-path flag for controlling static file locations

											
										
										
											2018-12-20 10:18:45 -06:00
+								    #crate-search{{background-image:url(\"{static_root_path}down-arrow{suffix}.svg\");}}\
-												Add arrow to the crate select box

											
										
										
											2018-11-29 01:29:49 +01:00
+								    </style>\
-												Small size reduction

											
										
										
											2018-04-14 17:13:46 +02:00
+								</head>\
 								<body class=\"rustdoc {css_class}\">\
-												rustdoc: Show nag box on IE10

Rustdoc doesn't work on IE11. It's been broken for months, it isn't supported
by the [tiered browser support list], it's even more severely broken on other
Rust websites, and IE11 doesn't support the `<details>` tag that we want
to use.

In the interest of honesty, let's give an actual error message for anyone
on IE11.

[tiered browser support list]: https://github.com/rust-lang/rfcs/blob/master/text/1985-tiered-browser-support.md

											
										
										
											2021-04-19 11:40:25 -07:00
+								    <!--[if lte IE 11]>\
-												Small size reduction

											
										
										
											2018-04-14 17:13:46 +02:00
+								    <div class=\"warning\">\
 								        This old browser is unsupported and will most likely display funky \
 								        things.\
 								    </div>\
 								    <![endif]-->\
 								    {before_content}\
 								    <nav class=\"sidebar\">\
-												Add ARIA role to sidebar toggle in Rustdoc

This indicates that the div is an interactive element, and makes the
sidebar toggle "clickable" in assistive technologies.

Fixes #82582

											
										
										
											2021-02-27 12:37:05 +02:00
+								        <div class=\"sidebar-menu\" role=\"button\">&#9776;</div>\
-												Small size reduction

											
										
										
											2018-04-14 17:13:46 +02:00
+								        {logo}\
 								        {sidebar}\
 								    </nav>\
 								    <div class=\"theme-picker\">\
-												Add aria roles for theme picker menu

											
										
										
											2020-10-30 13:35:41 -07:00
+								        <button id=\"theme-picker\" aria-label=\"Pick another theme!\" aria-haspopup=\"menu\">\
-												new --static-root-path flag for controlling static file locations

											
										
										
											2018-12-20 10:18:45 -06:00
+								            <img src=\"{static_root_path}brush{suffix}.svg\" \
-												Improve page load performance in rustdoc.

Add font-display: swap. Per https://web.dev/font-display/, this prevents
"flash of invisible text" during load by using a system font until the
custom font is available. I've noticed this flash of invisible text
occasionally when reading Rust docs.

Add an explicit height to icons (which already had an explicit width)
to allow browsers to lay out the page more accurately before the icons
have been loaded. https://web.dev/optimize-cls/.

Add min-width: 115px to the crate search dropdown. When the HTML first
loads, this dropdown includes only the text "All crates." Later, JS
loads the items underneath it, some of which are wider. That causes
the dropdown to get wider, causing a distracting reflow. This sets a
min-width based on the size that the dropdown eventually becomes based
on the crates on doc.rust-lang.org, reducing page movement during load.

											
										
										
											2021-02-19 17:54:41 -08:00
+								                 width=\"18\" height=\"18\" \
-												new --static-root-path flag for controlling static file locations

											
										
										
											2018-12-20 10:18:45 -06:00
+								                 alt=\"Pick another theme!\">\
-												Small size reduction

											
										
										
											2018-04-14 17:13:46 +02:00
+								        </button>\
-												Add aria roles for theme picker menu

											
										
										
											2020-10-30 13:35:41 -07:00
+								        <div id=\"theme-choices\" role=\"menu\"></div>\
-												Small size reduction

											
										
										
											2018-04-14 17:13:46 +02:00
+								    </div>\
 								    <nav class=\"sub\">\
-												rustdoc: fixes #64305: disable search field instead of hidding it

Signed-off-by: Maxime “pep” Buquet <pep@bouah.net>

											
										
										
											2019-11-11 16:54:45 +01:00
+								        <form class=\"search-form\">\
-												Small size reduction

											
										
										
											2018-04-14 17:13:46 +02:00
+								            <div class=\"search-container\">\
-												Add no-crate filter option on rustdoc

											
										
										
											2018-12-20 13:28:55 +01:00
+								                <div>{filter_crates}\
-												Add crate filtering

											
										
										
											2018-10-01 00:47:54 +02:00
+								                    <input class=\"search-input\" name=\"search\" \
-												rustdoc: fixes #64305: disable search field instead of hidding it

Signed-off-by: Maxime “pep” Buquet <pep@bouah.net>

											
										
										
											2019-11-11 16:54:45 +01:00
+								                           disabled \
-												Add crate filtering

											
										
										
											2018-10-01 00:47:54 +02:00
+								                           autocomplete=\"off\" \
 								                           spellcheck=\"false\" \
 								                           placeholder=\"Click or press ‘S’ to search, ‘?’ for more options…\" \
 								                           type=\"search\">\
 								                </div>\
-												Fixes submit event of the search input

In HTML, when a button follows an input, if the enter keep is pressed on the input, instead of sending the submit event to the input, it'll create a click event on the button following it, which in this case made the help popup show up whenever "enter" was pressed.

											
										
										
											2020-12-12 23:30:13 +01:00
+								                <button type=\"button\" class=\"help-button\">?</button>
-												Add rustdoc settings menu

											
										
										
											2018-04-13 22:54:09 +02:00
+								                <a id=\"settings-menu\" href=\"{root_path}settings.html\">\
-												new --static-root-path flag for controlling static file locations

											
										
										
											2018-12-20 10:18:45 -06:00
+								                    <img src=\"{static_root_path}wheel{suffix}.svg\" \
-												Improve page load performance in rustdoc.

Add font-display: swap. Per https://web.dev/font-display/, this prevents
"flash of invisible text" during load by using a system font until the
custom font is available. I've noticed this flash of invisible text
occasionally when reading Rust docs.

Add an explicit height to icons (which already had an explicit width)
to allow browsers to lay out the page more accurately before the icons
have been loaded. https://web.dev/optimize-cls/.

Add min-width: 115px to the crate search dropdown. When the HTML first
loads, this dropdown includes only the text "All crates." Later, JS
loads the items underneath it, some of which are wider. That causes
the dropdown to get wider, causing a distracting reflow. This sets a
min-width based on the size that the dropdown eventually becomes based
on the crates on doc.rust-lang.org, reducing page movement during load.

											
										
										
											2021-02-19 17:54:41 -08:00
+								                         width=\"18\" height=\"18\" \
-												new --static-root-path flag for controlling static file locations

											
										
										
											2018-12-20 10:18:45 -06:00
+								                         alt=\"Change settings\">\
-												Add rustdoc settings menu

											
										
										
											2018-04-13 22:54:09 +02:00
+								                </a>\
-												Small size reduction

											
										
										
											2018-04-14 17:13:46 +02:00
+								            </div>\
 								        </form>\
 								    </nav>\
 								    <section id=\"main\" class=\"content\">{content}</section>\
 								    <section id=\"search\" class=\"content hidden\"></section>\
 								    {after_content}\
-												Load rustdoc's JS search index on-demand.

Instead of being loaded on every page, the JS search index is now
loaded when either (a) there is a `?search=` param, or (b) the search
input is focused.

This saves both CPU and bandwidth. As of Feb 2021,
https://doc.rust-lang.org/search-index1.50.0.js is 273,838 bytes
gzipped or 2,544,939 bytes uncompressed. Evaluating it takes 445 ms
of CPU time in Chrome 88 on a i7-10710U CPU (out of a total ~2,100
ms page reload).

Generate separate JS file with crate names.

This is much smaller than the full search index, and is used in the "hot
path" to draw the page. In particular it's used to crate the dropdown
for the search bar, and to append a list of crates to the sidebar (on
some pages).

Skip early search that can bypass 500ms timeout.

This was occurring when someone had typed some text during the load of
search-index.js. Their query was usually not ready to execute, and the
search itself is fairly expensive, delaying the overall load, which
delayed the input / keyup events, which delayed eventually executing the
query.

											
										
										
											2021-02-19 17:22:30 -08:00
+								    <div id=\"rustdoc-vars\" data-root-path=\"{root_path}\" data-current-crate=\"{krate}\" \
-												Split search.js from search-index.js.

											
										
										
											2021-04-13 14:59:54 -07:00
+								       data-search-index-js=\"{root_path}search-index{suffix}.js\" \
-												Change root_path to static_root_path

Co-authored-by: Guillaume Gomez <guillaume1.gomez@gmail.com>
											
										
										
											2021-04-14 11:56:53 -07:00
+								       data-search-js=\"{static_root_path}search{suffix}.js\"></div>
-												new --static-root-path flag for controlling static file locations

											
										
										
											2018-12-20 10:18:45 -06:00
+								    <script src=\"{static_root_path}main{suffix}.js\"></script>\
-												Add source file sidebar

											
										
										
											2018-11-06 01:40:12 +01:00
+								    {extra_scripts}\
-												Small size reduction

											
										
										
											2018-04-14 17:13:46 +02:00
+								</body>\
 								</html>",
-												Format the world

											
										
										
											2019-12-22 17:42:04 -05:00
+								        css_extension = if layout.css_file_extension.is_some() {
 								            format!(
 								                "<link rel=\"stylesheet\" \
-												new --static-root-path flag for controlling static file locations

											
										
										
											2018-12-20 10:18:45 -06:00
+								                       type=\"text/css\" \
 								                       href=\"{static_root_path}theme{suffix}.css\">",
 								                static_root_path = static_root_path,
-												Format the world

											
										
										
											2019-12-22 17:42:04 -05:00
+								                suffix = page.resource_suffix
 								            )
 								        } else {
 								            String::new()
 								        },
 								        content = Buffer::html().to_display(t),
 								        static_root_path = static_root_path,
 								        root_path = page.root_path,
 								        css_class = page.css_class,
 								        logo = {
 								            if layout.logo.is_empty() {
 								                format!(
-												rustdoc tweaking

* Reuse memory
* simplify `next_def_id`, avoid multiple hashing and unnecessary lookups
* remove `all_fake_def_ids`, use the global map instead (probably not a good step toward parallelization, though...)
* convert `add_deref_target` to iterative implementation
* use `ArrayVec` where we know the max number of elements
* minor touchups here and there
* avoid building temporary vectors that get appended to other vectors

At most places I may or may not be doing the compiler's job is this PR.

											
										
										
											2021-01-30 01:02:18 +00:00
+								                    "<a href='{root}{path}index.html'>\
-												Only add a border for the rust logo

											
										
										
											2020-08-07 11:19:07 +02:00
+								                     <div class='logo-container rust-logo'>\
-												Fix image position and display

											
										
										
											2019-04-29 11:45:06 +02:00
+								                     <img src='{static_root_path}rust-logo{suffix}.png' alt='logo'></div></a>",
-												rustdoc tweaking

* Reuse memory
* simplify `next_def_id`, avoid multiple hashing and unnecessary lookups
* remove `all_fake_def_ids`, use the global map instead (probably not a good step toward parallelization, though...)
* convert `add_deref_target` to iterative implementation
* use `ArrayVec` where we know the max number of elements
* minor touchups here and there
* avoid building temporary vectors that get appended to other vectors

At most places I may or may not be doing the compiler's job is this PR.

											
										
										
											2021-01-30 01:02:18 +00:00
+								                    root = page.root_path,
 								                    path = ensure_trailing_slash(&layout.krate),
-												Format the world

											
										
										
											2019-12-22 17:42:04 -05:00
+								                    static_root_path = static_root_path,
 								                    suffix = page.resource_suffix
 								                )
 								            } else {
 								                format!(
-												rustdoc tweaking

* Reuse memory
* simplify `next_def_id`, avoid multiple hashing and unnecessary lookups
* remove `all_fake_def_ids`, use the global map instead (probably not a good step toward parallelization, though...)
* convert `add_deref_target` to iterative implementation
* use `ArrayVec` where we know the max number of elements
* minor touchups here and there
* avoid building temporary vectors that get appended to other vectors

At most places I may or may not be doing the compiler's job is this PR.

											
										
										
											2021-01-30 01:02:18 +00:00
+								                    "<a href='{root}{path}index.html'>\
 								                     <div class='logo-container'><img src='{logo}' alt='logo'></div></a>",
 								                    root = page.root_path,
 								                    path = ensure_trailing_slash(&layout.krate),
 								                    logo = layout.logo
-												Format the world

											
										
										
											2019-12-22 17:42:04 -05:00
+								                )
 								            }
 								        },
 								        title = page.title,
 								        description = page.description,
 								        keywords = page.keywords,
 								        favicon = if layout.favicon.is_empty() {
 								            format!(
-												Use theme-adaptive SVG favicon from other Rust sites

											
										
										
											2020-09-23 21:31:27 -04:00
+								                r##"<link rel="icon" type="image/svg+xml" href="{static_root_path}favicon{suffix}.svg">
 								<link rel="alternate icon" type="image/png" href="{static_root_path}favicon-16x16{suffix}.png">
 								<link rel="alternate icon" type="image/png" href="{static_root_path}favicon-32x32{suffix}.png">"##,
-												Format the world

											
										
										
											2019-12-22 17:42:04 -05:00
+								                static_root_path = static_root_path,
 								                suffix = page.resource_suffix
 								            )
 								        } else {
 								            format!(r#"<link rel="shortcut icon" href="{}">"#, layout.favicon)
 								        },
 								        in_header = layout.external_html.in_header,
 								        before_content = layout.external_html.before_content,
 								        after_content = layout.external_html.after_content,
 								        sidebar = Buffer::html().to_display(sidebar),
 								        krate = layout.krate,
-												rustdoc: Provide a way to set the default settings from Rust code

rustdoc has various user-configurable preferences.  These are recorded
in web Local Storage (where available).  But we want to provide a way
to configure the default default, including for when web storage is
not available.

getSettingValue is the function responsible for looking up these
settings.  Here we make it fall back some in-DOM data, which
ultimately comes from RenderOptions.default_settings.

Using HTML data atrtributes is fairly convenient here, dsspite the
need to transform between snake and kebab case to avoid the DOM
converting kebab case to camel case (!)

We cache the element and dataset lookup in a global variable, to
ensure that getSettingValue remains fast.

The DOM representation has to be in an element which precedes the
inclusion of storage.js.  That means it has to be in the <head> and we
should not use an empty <div> as the container (although most browsers
will accept that).  An empty <script> element provides a convenient
and harmless container object.  <meta> would be another possibility
but runs a greater risk of having unwanted behaviours on weird
browsers.

We trust the RenderOptions not to contain unhelpful setting names,
which don't fit nicely into an HTML attribute.  It's awkward to quote
dataset keys.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

											
										
										
											2020-09-23 22:44:54 +01:00
+								        default_settings = layout
 								            .default_settings
 								            .iter()
-												rustdoc: Fix some nits

* Remove a needless comma in the Rust code
* Replace double spaces after full stops with single spaces

Requested-by: @GuillaumeGomez
Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

											
										
										
											2020-10-28 20:12:15 +00:00
+								            .map(|(k, v)| format!(r#" data-{}="{}""#, k.replace('-', "_"), Escape(v)))
-												rustdoc: Provide a way to set the default settings from Rust code

rustdoc has various user-configurable preferences.  These are recorded
in web Local Storage (where available).  But we want to provide a way
to configure the default default, including for when web storage is
not available.

getSettingValue is the function responsible for looking up these
settings.  Here we make it fall back some in-DOM data, which
ultimately comes from RenderOptions.default_settings.

Using HTML data atrtributes is fairly convenient here, dsspite the
need to transform between snake and kebab case to avoid the DOM
converting kebab case to camel case (!)

We cache the element and dataset lookup in a global variable, to
ensure that getSettingValue remains fast.

The DOM representation has to be in an element which precedes the
inclusion of storage.js.  That means it has to be in the <head> and we
should not use an empty <div> as the container (although most browsers
will accept that).  An empty <script> element provides a convenient
and harmless container object.  <meta> would be another possibility
but runs a greater risk of having unwanted behaviours on weird
browsers.

We trust the RenderOptions not to contain unhelpful setting names,
which don't fit nicely into an HTML attribute.  It's awkward to quote
dataset keys.

Signed-off-by: Ian Jackson <ijackson@chiark.greenend.org.uk>

											
										
										
											2020-09-23 22:44:54 +01:00
+								            .collect::<String>(),
-												Clean up handling of style files in rustdoc
Disable all themes other than `light.css` to prevent rule conflicts

											
										
										
											2020-07-12 14:37:22 -04:00
+								        style_files = style_files
-												Format the world

											
										
										
											2019-12-22 17:42:04 -05:00
+								            .iter()
-												Clean up handling of style files in rustdoc
Disable all themes other than `light.css` to prevent rule conflicts

											
										
										
											2020-07-12 14:37:22 -04:00
+								            .filter_map(|t| {
 								                if let Some(stem) = t.path.file_stem() { Some((stem, t.disabled)) } else { None }
 								            })
 								            .filter_map(|t| {
 								                if let Some(path) = t.0.to_str() { Some((path, t.1)) } else { None }
 								            })
-												Format the world

											
										
										
											2019-12-22 17:42:04 -05:00
+								            .map(|t| format!(
-												Clean up handling of style files in rustdoc
Disable all themes other than `light.css` to prevent rule conflicts

											
										
										
											2020-07-12 14:37:22 -04:00
+								                r#"<link rel="stylesheet" type="text/css" href="{}.css" {} {}>"#,
 								                Escape(&format!("{}{}{}", static_root_path, t.0, page.resource_suffix)),
 								                if t.1 { "disabled" } else { "" },
 								                if t.0 == "light" { "id=\"themeStyle\"" } else { "" }
-												Format the world

											
										
										
											2019-12-22 17:42:04 -05:00
+								            ))
 								            .collect::<String>(),
 								        suffix = page.resource_suffix,
-												rustdoc tweaking

* Reuse memory
* simplify `next_def_id`, avoid multiple hashing and unnecessary lookups
* remove `all_fake_def_ids`, use the global map instead (probably not a good step toward parallelization, though...)
* convert `add_deref_target` to iterative implementation
* use `ArrayVec` where we know the max number of elements
* minor touchups here and there
* avoid building temporary vectors that get appended to other vectors

At most places I may or may not be doing the compiler's job is this PR.

											
										
										
											2021-01-30 01:02:18 +00:00
+								        extra_scripts = page
-												Format the world

											
										
										
											2019-12-22 17:42:04 -05:00
+								            .static_extra_scripts
 								            .iter()
 								            .map(|e| {
 								                format!(
 								                    "<script src=\"{static_root_path}{extra_script}.js\"></script>",
 								                    static_root_path = static_root_path,
 								                    extra_script = e
 								                )
 								            })
-												rustdoc tweaking

* Reuse memory
* simplify `next_def_id`, avoid multiple hashing and unnecessary lookups
* remove `all_fake_def_ids`, use the global map instead (probably not a good step toward parallelization, though...)
* convert `add_deref_target` to iterative implementation
* use `ArrayVec` where we know the max number of elements
* minor touchups here and there
* avoid building temporary vectors that get appended to other vectors

At most places I may or may not be doing the compiler's job is this PR.

											
										
										
											2021-01-30 01:02:18 +00:00
+								            .chain(page.extra_scripts.iter().map(|e| {
-												Format the world

											
										
										
											2019-12-22 17:42:04 -05:00
+								                format!(
 								                    "<script src=\"{root_path}{extra_script}.js\"></script>",
 								                    root_path = page.root_path,
 								                    extra_script = e
 								                )
-												rustdoc tweaking

* Reuse memory
* simplify `next_def_id`, avoid multiple hashing and unnecessary lookups
* remove `all_fake_def_ids`, use the global map instead (probably not a good step toward parallelization, though...)
* convert `add_deref_target` to iterative implementation
* use `ArrayVec` where we know the max number of elements
* minor touchups here and there
* avoid building temporary vectors that get appended to other vectors

At most places I may or may not be doing the compiler's job is this PR.

											
										
										
											2021-01-30 01:02:18 +00:00
+								            }))
-												Format the world

											
										
										
											2019-12-22 17:42:04 -05:00
+								            .collect::<String>(),
 								        filter_crates = if layout.generate_search_filter {
 								            "<select id=\"crate-search\">\
-												Fix strings indent

											
										
										
											2020-08-31 13:16:50 +02:00
+								                 <option value=\"All crates\">All crates</option>\
 								             </select>"
-												Format the world

											
										
										
											2019-12-22 17:42:04 -05:00
+								        } else {
 								            ""
 								        },
-												Remove unnecessary Buffer in layout::render

											
										
										
											2019-08-31 08:52:04 -04:00
+								    )
-												Implement a web backend for rustdoc_ng

This large commit implements and `html` output option for rustdoc_ng. The
executable has been altered to be invoked as "rustdoc_ng html <crate>" and
it will dump everything into the local "doc" directory. JSON can still be
generated by changing 'html' to 'json'.

This also fixes a number of bugs in rustdoc_ng relating to comment stripping,
along with some other various issues that I found along the way.

The `make doc` command has been altered to generate the new documentation into
the `doc/ng/$(CRATE)` directories.

											
										
										
											2013-09-18 22:18:38 -07:00
+								}
-												Make all rustdoc functions and structs crate-private

This gives warnings about dead code.

											
										
										
											2020-11-14 17:59:58 -05:00
+								crate fn redirect(url: &str) -> String {
-												rustdoc: Preserve query/fragment in redirects whenever possible.

We heavily rely on queries and fragments in the URL structure, so
it is desired to preserve them even in the redirects. The generated
redirect pages try to preserve them with scripts, which take
precedence over the original `Refresh` metadata. Non-scripting
browsers would continue to work (with no queries and fragments).

											
										
										
											2014-12-04 12:48:16 +09:00
+								    // <script> triggers a redirect before refresh, so this is fine.
-												Create buffers in top-level rendering

This avoids needlessly creating and threading the buffers through when
we only use them once.

											
										
										
											2019-08-30 10:35:14 -04:00
+								    format!(
-												Format the world

											
										
										
											2019-12-22 17:42:04 -05:00
+								        r##"<!DOCTYPE html>
-												rustdoc: Fix cross-crate links to reexported items

Cross crate links can target items which are not rendered in the documentation.
If the item is reexported at a higher level, the destination of the link (a
concatenation of the fully qualified name) may actually lead to nowhere. This
fixes this problem by altering rustdoc to emit pages which redirect to the local
copy of the reexported structure.

cc #14515
Closes #14137

											
										
										
											2014-05-29 13:50:47 -07:00
+								<html lang="en">
 								<head>
 								    <meta http-equiv="refresh" content="0;URL={url}">
 								</head>
 								<body>
-												rustdoc: Preserve query/fragment in redirects whenever possible.

We heavily rely on queries and fragments in the URL structure, so
it is desired to preserve them even in the redirects. The generated
redirect pages try to preserve them with scripts, which take
precedence over the original `Refresh` metadata. Non-scripting
browsers would continue to work (with no queries and fragments).

											
										
										
											2014-12-04 12:48:16 +09:00
+								    <p>Redirecting to <a href="{url}">{url}</a>...</p>
 								    <script>location.replace("{url}" + location.search + location.hash);</script>
-												rustdoc: Fix cross-crate links to reexported items

Cross crate links can target items which are not rendered in the documentation.
If the item is reexported at a higher level, the destination of the link (a
concatenation of the fully qualified name) may actually lead to nowhere. This
fixes this problem by altering rustdoc to emit pages which redirect to the local
copy of the reexported structure.

cc #14515
Closes #14137

											
										
										
											2014-05-29 13:50:47 -07:00
+								</body>
 								</html>"##,
-												Format the world

											
										
										
											2019-12-22 17:42:04 -05:00
+								        url = url,
-												rustdoc: Fix cross-crate links to reexported items

Cross crate links can target items which are not rendered in the documentation.
If the item is reexported at a higher level, the destination of the link (a
concatenation of the fully qualified name) may actually lead to nowhere. This
fixes this problem by altering rustdoc to emit pages which redirect to the local
copy of the reexported structure.

cc #14515
Closes #14137

											
										
										
											2014-05-29 13:50:47 -07:00
+								    )
 								}