rust/src/librustdoc/html/layout.rs

use std::collections::HashMap;
use std::path::PathBuf;

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: HashMap<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>\
    <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 8]>\
    <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\">&#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\" \
                 alt=\"Pick another theme!\">\
        </button>\
        <div id=\"theme-choices\" role=\"menu\"></div>\
    </div>\
    <script src=\"{static_root_path}theme{suffix}.js\"></script>\
    <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\" \
                         alt=\"Change settings\">\
                </a>\
            </div>\
        </form>\
    </nav>\
    <section id=\"main\" class=\"content\">{content}</section>\
    <section id=\"search\" class=\"content hidden\"></section>\
    <section class=\"footer\"></section>\
    {after_content}\
    <div id=\"rustdoc-vars\" data-root-path=\"{root_path}\" data-current-crate=\"{krate}\"></div>
    <script src=\"{static_root_path}main{suffix}.js\"></script>\
    {static_extra_scripts}\
    {extra_scripts}\
    <script defer src=\"{root_path}search-index{suffix}.js\"></script>\
</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 = {
            let p = format!("{}{}", page.root_path, layout.krate);
            let p = ensure_trailing_slash(&p);
            if layout.logo.is_empty() {
                format!(
                    "<a href='{path}index.html'>\
                     <div class='logo-container rust-logo'>\
                     <img src='{static_root_path}rust-logo{suffix}.png' alt='logo'></div></a>",
                    path = p,
                    static_root_path = static_root_path,
                    suffix = page.resource_suffix
                )
            } else {
                format!(
                    "<a href='{}index.html'>\
                     <div class='logo-container'><img src='{}' alt='logo'></div></a>",
                    p, 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,
        static_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
                )
            })
            .collect::<String>(),
        extra_scripts = 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,
    )
}
-												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
+								use std::collections::HashMap;
-												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
-												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,
 								    crate default_settings: HashMap<String, String>,
 								    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>\
 								    <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}\">\
 								    <!--[if lte IE 8]>\
 								    <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\">&#9776;</div>\
 								        {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\" \
 								                 width=\"18\" \
 								                 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>\
-												new --static-root-path flag for controlling static file locations

											
										
										
											2018-12-20 10:18:45 -06:00
+								    <script src=\"{static_root_path}theme{suffix}.js\"></script>\
-												Small size reduction

											
										
										
											2018-04-14 17:13:46 +02:00
+								    <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\" \
 								                         width=\"18\" \
 								                         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>\
 								    <section class=\"footer\"></section>\
 								    {after_content}\
-												Remove inline script tags

											
										
										
											2021-01-18 12:03:53 +01:00
+								    <div id=\"rustdoc-vars\" data-root-path=\"{root_path}\" data-current-crate=\"{krate}\"></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>\
-												split extra_scripts to handle root_path shenanigans

											
										
										
											2018-12-20 10:57:03 -06:00
+								    {static_extra_scripts}\
-												Add source file sidebar

											
										
										
											2018-11-06 01:40:12 +01:00
+								    {extra_scripts}\
-												Apply resource-suffix to search-index and source-files scripts as well

											
										
										
											2019-04-07 18:09:28 +02:00
+								    <script defer src=\"{root_path}search-index{suffix}.js\"></script>\
-												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 = {
 								            let p = format!("{}{}", page.root_path, layout.krate);
 								            let p = ensure_trailing_slash(&p);
 								            if layout.logo.is_empty() {
 								                format!(
 								                    "<a href='{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>",
-												Format the world

											
										
										
											2019-12-22 17:42:04 -05:00
+								                    path = p,
 								                    static_root_path = static_root_path,
 								                    suffix = page.resource_suffix
 								                )
 								            } else {
 								                format!(
 								                    "<a href='{}index.html'>\
-												Fix image position and display

											
										
										
											2019-04-29 11:45:06 +02:00
+								                     <div class='logo-container'><img src='{}' alt='logo'></div></a>",
-												Format the world

											
										
										
											2019-12-22 17:42:04 -05:00
+								                    p, layout.logo
 								                )
 								            }
 								        },
 								        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,
 								        static_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
 								                )
 								            })
 								            .collect::<String>(),
 								        extra_scripts = 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\">\
-												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
+								    )
 								}