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     <style type=\"text/css\">\
  61     #crate-search{{background-image:url(\"{root_path}down-arrow{suffix}.svg\");}}\
  62     </style>\
  63 </head>\
  64 <body class=\"rustdoc {css_class}\">\
  65     <!--[if lte IE 8]>\
  66     <div class=\"warning\">\
  67         This old browser is unsupported and will most likely display funky \
  68         things.\
  69     </div>\
  70     <![endif]-->\
  71     {before_content}\
  72     <nav class=\"sidebar\">\
  73         <div class=\"sidebar-menu\">&#9776;</div>\
  74         {logo}\
  75         {sidebar}\
  76     </nav>\
  77     <div class=\"theme-picker\">\
  78         <button id=\"theme-picker\" aria-label=\"Pick another theme!\">\
  79             <img src=\"{root_path}brush{suffix}.svg\" width=\"18\" alt=\"Pick another theme!\">\
  80         </button>\
  81         <div id=\"theme-choices\"></div>\
  82     </div>\
  83     <script src=\"{root_path}theme{suffix}.js\"></script>\
  84     <nav class=\"sub\">\
  85         <form class=\"search-form js-only\">\
  86             <div class=\"search-container\">\
  87                 <div>\
  88                     <select id=\"crate-search\">\
  89                         <option value=\"All crates\">All crates</option>\
  90                     </select>\
  91                     <input class=\"search-input\" name=\"search\" \
  92                            autocomplete=\"off\" \
  93                            spellcheck=\"false\" \
  94                            placeholder=\"Click or press ‘S’ to search, ‘?’ for more options…\" \
  95                            type=\"search\">\
  96                 </div>\
  97                 <a id=\"settings-menu\" href=\"{root_path}settings.html\">\
  98                     <img src=\"{root_path}wheel{suffix}.svg\" width=\"18\" alt=\"Change settings\">\
  99                 </a>\
 100             </div>\
 101         </form>\
 102     </nav>\
 103     <section id=\"main\" class=\"content\">{content}</section>\
 104     <section id=\"search\" class=\"content hidden\"></section>\
 105     <section class=\"footer\"></section>\
 106     <aside id=\"help\" class=\"hidden\">\
 107         <div>\
 108             <h1 class=\"hidden\">Help</h1>\
 109             <div class=\"shortcuts\">\
 110                 <h2>Keyboard Shortcuts</h2>\
 111                 <dl>\
 112                     <dt><kbd>?</kbd></dt>\
 113                     <dd>Show this help dialog</dd>\
 114                     <dt><kbd>S</kbd></dt>\
 115                     <dd>Focus the search field</dd>\
 116                     <dt><kbd>↑</kbd></dt>\
 117                     <dd>Move up in search results</dd>\
 118                     <dt><kbd>↓</kbd></dt>\
 119                     <dd>Move down in search results</dd>\
 120                     <dt><kbd>↹</kbd></dt>\
 121                     <dd>Switch tab</dd>\
 122                     <dt><kbd>&#9166;</kbd></dt>\
 123                     <dd>Go to active search result</dd>\
 124                     <dt><kbd>+</kbd></dt>\
 125                     <dd>Expand all sections</dd>\
 126                     <dt><kbd>-</kbd></dt>\
 127                     <dd>Collapse all sections</dd>\
 128                 </dl>\
 129             </div>\
 130             <div class=\"infos\">\
 131                 <h2>Search Tricks</h2>\
 132                 <p>\
 133                     Prefix searches with a type followed by a colon (e.g. \
 134                     <code>fn:</code>) to restrict the search to a given type.\
 135                 </p>\
 136                 <p>\
 137                     Accepted types are: <code>fn</code>, <code>mod</code>, \
 138                     <code>struct</code>, <code>enum</code>, \
 139                     <code>trait</code>, <code>type</code>, <code>macro</code>, \
 140                     and <code>const</code>.\
 141                 </p>\
 142                 <p>\
 143                     Search functions by type signature (e.g. \
 144                     <code>vec -> usize</code> or <code>* -> vec</code>)\
 145                 </p>\
 146                 <p>\
 147                     Search multiple things at once by splitting your query with comma (e.g. \
 148                     <code>str,u8</code> or <code>String,struct:Vec,test</code>)\
 149                 </p>\
 150             </div>\
 151         </div>\
 152     </aside>\
 153     {after_content}\
 154     <script>\
 155         window.rootPath = \"{root_path}\";\
 156         window.currentCrate = \"{krate}\";\
 157     </script>\
 158     <script src=\"{root_path}aliases.js\"></script>\
 159     <script src=\"{root_path}main{suffix}.js\"></script>\
 160     {extra_scripts}\
 161     <script defer src=\"{root_path}search-index.js\"></script>\
 162 </body>\
 163 </html>",
 164     css_extension = if css_file_extension {
 165         format!("<link rel=\"stylesheet\" type=\"text/css\" href=\"{root_path}theme{suffix}.css\">",
 166                 root_path = page.root_path,
 167                 suffix=page.resource_suffix)
 168     } else {
 169         String::new()
 170     },
 171     content   = *t,
 172     root_path = page.root_path,
 173     css_class = page.css_class,
 174     logo      = if layout.logo.is_empty() {
 175         String::new()
 176     } else {
 177         format!("<a href='{}{}/index.html'>\
 178                  <img src='{}' alt='logo' width='100'></a>",
 179                 page.root_path, layout.krate,
 180                 layout.logo)
 181     },
 182     title     = page.title,
 183     description = page.description,
 184     keywords = page.keywords,
 185     favicon   = if layout.favicon.is_empty() {
 186         String::new()
 187     } else {
 188         format!(r#"<link rel="shortcut icon" href="{}">"#, layout.favicon)
 189     },
 190     in_header = layout.external_html.in_header,
 191     before_content = layout.external_html.before_content,
 192     after_content = layout.external_html.after_content,
 193     sidebar   = *sidebar,
 194     krate     = layout.krate,
 195     themes = themes.iter()
 196                    .filter_map(|t| t.file_stem())
 197                    .filter_map(|t| t.to_str())
 198                    .map(|t| format!(r#"<link rel="stylesheet" type="text/css" href="{}{}{}.css">"#,
 199                                     page.root_path,
 200                                     t,
 201                                     page.resource_suffix))
 202                    .collect::<String>(),
 203     suffix=page.resource_suffix,
 204     extra_scripts=extra_scripts.iter().map(|e| {
 205         format!("<script src=\"{root_path}{extra_script}.js\"></script>",
 206                 root_path=page.root_path,
 207                 extra_script=e)
 208     }).collect::<String>(),
 209     )
 210 }
 211
 212 pub fn redirect(dst: &mut dyn io::Write, url: &str) -> io::Result<()> {
 213     // <script> triggers a redirect before refresh, so this is fine.
 214     write!(dst,
 215 r##"<!DOCTYPE html>
 216 <html lang="en">
 217 <head>
 218     <meta http-equiv="refresh" content="0;URL={url}">
 219 </head>
 220 <body>
 221     <p>Redirecting to <a href="{url}">{url}</a>...</p>
 222     <script>location.replace("{url}" + location.search + location.hash);</script>
 223 </body>
 224 </html>"##,
 225     url = url,
 226     )
 227 }