src/librustdoc/html/layout.rs

   1 // Copyright 2013 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 use std::fmt;
  12 use std::io;
  13 use std::path::PathBuf;
  14
  15 use externalfiles::ExternalHtml;
  16
  17 #[derive(Clone)]
  18 pub struct Layout {
  19     pub logo: String,
  20     pub favicon: String,
  21     pub external_html: ExternalHtml,
  22     pub krate: String,
  23 }
  24
  25 pub struct Page<'a> {
  26     pub title: &'a str,
  27     pub css_class: &'a str,
  28     pub root_path: &'a str,
  29     pub description: &'a str,
  30     pub keywords: &'a str,
  31     pub resource_suffix: &'a str,
  32 }
  33
  34 pub fn render<T: fmt::Display, S: fmt::Display>(
  35     dst: &mut dyn io::Write, layout: &Layout, page: &Page, sidebar: &S, t: &T,
  36     css_file_extension: bool, themes: &[PathBuf], extra_scripts: &[&str])
  37     -> io::Result<()>
  38 {
  39     write!(dst,
  40 "<!DOCTYPE html>\
  41 <html lang=\"en\">\
  42 <head>\
  43     <meta charset=\"utf-8\">\
  44     <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\
  45     <meta name=\"generator\" content=\"rustdoc\">\
  46     <meta name=\"description\" content=\"{description}\">\
  47     <meta name=\"keywords\" content=\"{keywords}\">\
  48     <title>{title}</title>\
  49     <link rel=\"stylesheet\" type=\"text/css\" href=\"{root_path}normalize{suffix}.css\">\
  50     <link rel=\"stylesheet\" type=\"text/css\" href=\"{root_path}rustdoc{suffix}.css\" \
  51           id=\"mainThemeStyle\">\
  52     {themes}\
  53     <link rel=\"stylesheet\" type=\"text/css\" href=\"{root_path}dark{suffix}.css\">\
  54     <link rel=\"stylesheet\" type=\"text/css\" href=\"{root_path}light{suffix}.css\" \
  55           id=\"themeStyle\">\
  56     <script src=\"{root_path}storage{suffix}.js\"></script>\
  57     {css_extension}\
  58     {favicon}\
  59     {in_header}\
  60 </head>\
  61 <body class=\"rustdoc {css_class}\">\
  62     <!--[if lte IE 8]>\
  63     <div class=\"warning\">\
  64         This old browser is unsupported and will most likely display funky \
  65         things.\
  66     </div>\
  67     <![endif]-->\
  68     {before_content}\
  69     <nav class=\"sidebar\">\
  70         <div class=\"sidebar-menu\">&#9776;</div>\
  71         {logo}\
  72         {sidebar}\
  73     </nav>\
  74     <div class=\"theme-picker\">\
  75         <button id=\"theme-picker\" aria-label=\"Pick another theme!\">\
  76             <img src=\"{root_path}brush{suffix}.svg\" width=\"18\" alt=\"Pick another theme!\">\
  77         </button>\
  78         <div id=\"theme-choices\"></div>\
  79     </div>\
  80     <script src=\"{root_path}theme{suffix}.js\"></script>\
  81     <nav class=\"sub\">\
  82         <form class=\"search-form js-only\">\
  83             <div class=\"search-container\">\
  84                 <input class=\"search-input\" name=\"search\" \
  85                        autocomplete=\"off\" \
  86                        spellcheck=\"false\" \
  87                        placeholder=\"Click or press ‘S’ to search, ‘?’ for more options…\" \
  88                        type=\"search\">\
  89                 <a id=\"settings-menu\" href=\"{root_path}settings.html\">\
  90                     <img src=\"{root_path}wheel{suffix}.svg\" width=\"18\" alt=\"Change settings\">\
  91                 </a>\
  92             </div>\
  93         </form>\
  94     </nav>\
  95     <section id=\"main\" class=\"content\">{content}</section>\
  96     <section id=\"search\" class=\"content hidden\"></section>\
  97     <section class=\"footer\"></section>\
  98     <aside id=\"help\" class=\"hidden\">\
  99         <div>\
 100             <h1 class=\"hidden\">Help</h1>\
 101             <div class=\"shortcuts\">\
 102                 <h2>Keyboard Shortcuts</h2>\
 103                 <dl>\
 104                     <dt><kbd>?</kbd></dt>\
 105                     <dd>Show this help dialog</dd>\
 106                     <dt><kbd>S</kbd></dt>\
 107                     <dd>Focus the search field</dd>\
 108                     <dt><kbd>↑</kbd></dt>\
 109                     <dd>Move up in search results</dd>\
 110                     <dt><kbd>↓</kbd></dt>\
 111                     <dd>Move down in search results</dd>\
 112                     <dt><kbd>↹</kbd></dt>\
 113                     <dd>Switch tab</dd>\
 114                     <dt><kbd>&#9166;</kbd></dt>\
 115                     <dd>Go to active search result</dd>\
 116                     <dt><kbd>+</kbd></dt>\
 117                     <dd>Expand all sections</dd>\
 118                     <dt><kbd>-</kbd></dt>\
 119                     <dd>Collapse all sections</dd>\
 120                 </dl>\
 121             </div>\
 122             <div class=\"infos\">\
 123                 <h2>Search Tricks</h2>\
 124                 <p>\
 125                     Prefix searches with a type followed by a colon (e.g. \
 126                     <code>fn:</code>) to restrict the search to a given type.\
 127                 </p>\
 128                 <p>\
 129                     Accepted types are: <code>fn</code>, <code>mod</code>, \
 130                     <code>struct</code>, <code>enum</code>, \
 131                     <code>trait</code>, <code>type</code>, <code>macro</code>, \
 132                     and <code>const</code>.\
 133                 </p>\
 134                 <p>\
 135                     Search functions by type signature (e.g. \
 136                     <code>vec -> usize</code> or <code>* -> vec</code>)\
 137                 </p>\
 138                 <p>\
 139                     Search multiple things at once by splitting your query with comma (e.g. \
 140                     <code>str,u8</code> or <code>String,struct:Vec,test</code>)\
 141                 </p>\
 142             </div>\
 143         </div>\
 144     </aside>\
 145     {after_content}\
 146     <script>\
 147         window.rootPath = \"{root_path}\";\
 148         window.currentCrate = \"{krate}\";\
 149     </script>\
 150     <script src=\"{root_path}aliases.js\"></script>\
 151     <script src=\"{root_path}main{suffix}.js\"></script>\
 152     {extra_scripts}\
 153     <script defer src=\"{root_path}search-index.js\"></script>\
 154 </body>\
 155 </html>",
 156     css_extension = if css_file_extension {
 157         format!("<link rel=\"stylesheet\" type=\"text/css\" href=\"{root_path}theme{suffix}.css\">",
 158                 root_path = page.root_path,
 159                 suffix=page.resource_suffix)
 160     } else {
 161         String::new()
 162     },
 163     content   = *t,
 164     root_path = page.root_path,
 165     css_class = page.css_class,
 166     logo      = if layout.logo.is_empty() {
 167         String::new()
 168     } else {
 169         format!("<a href='{}{}/index.html'>\
 170                  <img src='{}' alt='logo' width='100'></a>",
 171                 page.root_path, layout.krate,
 172                 layout.logo)
 173     },
 174     title     = page.title,
 175     description = page.description,
 176     keywords = page.keywords,
 177     favicon   = if layout.favicon.is_empty() {
 178         String::new()
 179     } else {
 180         format!(r#"<link rel="shortcut icon" href="{}">"#, layout.favicon)
 181     },
 182     in_header = layout.external_html.in_header,
 183     before_content = layout.external_html.before_content,
 184     after_content = layout.external_html.after_content,
 185     sidebar   = *sidebar,
 186     krate     = layout.krate,
 187     themes = themes.iter()
 188                    .filter_map(|t| t.file_stem())
 189                    .filter_map(|t| t.to_str())
 190                    .map(|t| format!(r#"<link rel="stylesheet" type="text/css" href="{}{}{}.css">"#,
 191                                     page.root_path,
 192                                     t,
 193                                     page.resource_suffix))
 194                    .collect::<String>(),
 195     suffix=page.resource_suffix,
 196     extra_scripts=extra_scripts.iter().map(|e| {
 197         format!("<script src=\"{root_path}{extra_script}.js\"></script>",
 198                 root_path=page.root_path,
 199                 extra_script=e)
 200     }).collect::<String>(),
 201     )
 202 }
 203
 204 pub fn redirect(dst: &mut dyn io::Write, url: &str) -> io::Result<()> {
 205     // <script> triggers a redirect before refresh, so this is fine.
 206     write!(dst,
 207 r##"<!DOCTYPE html>
 208 <html lang="en">
 209 <head>
 210     <meta http-equiv="refresh" content="0;URL={url}">
 211 </head>
 212 <body>
 213     <p>Redirecting to <a href="{url}">{url}</a>...</p>
 214     <script>location.replace("{url}" + location.search + location.hash);</script>
 215 </body>
 216 </html>"##,
 217     url = url,
 218     )
 219 }