Auto merge of #54733 - GuillaumeGomez:stabilize-rustdoc-theme, r=ollie27,Dylan-DPC

Stabilize rustdoc theme options

Closes #54730

This PR stabilizes the `--themes` (now `--theme`) and `--theme-checker` (now `--check-theme`) options, for allowing users to add custom themes to their documentation.

Rustdoc includes two themes by default: `light` and `dark`. Using the `--theme` option, you can give rustdoc a CSS file to include as an extra theme for that render. Themes are named after the CSS file used, so using `--theme /path/to/your/custom-theme.css` will add a theme called `custom-theme` to the documentation.

Even though the CLI flag to add a theme is getting stabilized, there's no guarantee that a theme file will always have the same effect on documentation generated with future versions of rustdoc. To aid in ensuring that a theme will work, the flag `--check-theme` is also available, which compares the CSS rules defined by a custom theme against the ones used in the `light` theme. If the `light` theme defines a CSS rule that the custom theme does not, rustdoc will report an error. (Rustdoc also performs this check for themes given to `--theme`, but only reports a warning when a difference is found.)

src/librustdoc/html/layout.rs

@@ -1,6 +1,7 @@
 use std::path::PathBuf;
 
 use crate::externalfiles::ExternalHtml;
+use crate::html::escape::Escape;
 use crate::html::render::ensure_trailing_slash;
 use crate::html::format::{Buffer, Print};
 
@@ -166,10 +167,11 @@ pub fn render<T: Print, S: Print>(
     themes = themes.iter()
                    .filter_map(|t| t.file_stem())
                    .filter_map(|t| t.to_str())
-                   .map(|t| format!(r#"<link rel="stylesheet" type="text/css" href="{}{}{}.css">"#,
-                                    static_root_path,
-                                    t,
-                                    page.resource_suffix))
+                   .map(|t| format!(r#"<link rel="stylesheet" type="text/css" href="{}.css">"#,
+                                    Escape(&format!("{}{}{}",
+                                                    static_root_path,
+                                                    t,
+                                                    page.resource_suffix))))
                    .collect::<String>(),
     suffix=page.resource_suffix,
     static_extra_scripts=page.static_extra_scripts.iter().map(|e| {

src/librustdoc/html/render.rs

@@ -633,19 +633,16 @@ function handleThemeButtonsBlur(e) {{
 
 themePicker.onclick = switchThemeButtonState;
 themePicker.onblur = handleThemeButtonsBlur;
-[{}].forEach(function(item) {{
+{}.forEach(function(item) {{
     var but = document.createElement('button');
-    but.innerHTML = item;
+    but.textContent = item;
     but.onclick = function(el) {{
         switchTheme(currentTheme, mainTheme, item, true);
     }};
     but.onblur = handleThemeButtonsBlur;
     themes.appendChild(but);
 }});"#,
-                 themes.iter()
-                       .map(|s| format!("\"{}\"", s))
-                       .collect::<Vec<String>>()
-                       .join(","));
+                 as_json(&themes));
     write(cx.dst.join(&format!("theme{}.js", cx.shared.resource_suffix)),
           theme_js.as_bytes()
     )?;

src/librustdoc/html/static_files.rs

@@ -59,7 +59,7 @@ pub static RUST_FAVICON: &'static [u8] = include_bytes!("static/favicon.ico");
 /// The built-in themes given to every documentation site.
 pub mod themes {
     /// The "light" theme, selected by default when no setting is available. Used as the basis for
-    /// the `--theme-checker` functionality.
+    /// the `--check-theme` functionality.
     pub static LIGHT: &'static str = include_str!("static/themes/light.css");
 
     /// The "dark" theme.