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