From 117169799ffb6df9a86f4d3e933968274022bdd3 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Mon, 29 Aug 2022 18:05:21 +0200 Subject: [PATCH] Generate error index with mdbook instead of raw HTML pages --- Cargo.lock | 2 +- src/bootstrap/doc.rs | 2 +- src/tools/error_index_generator/Cargo.toml | 2 +- .../error_index_generator/book_config.toml | 19 ++ .../error_index_generator/error-index.css | 38 +++ .../error_index_generator/error-index.js | 9 + src/tools/error_index_generator/main.rs | 285 +++++++++--------- src/tools/error_index_generator/redirect.js | 10 + 8 files changed, 220 insertions(+), 147 deletions(-) create mode 100644 src/tools/error_index_generator/book_config.toml create mode 100644 src/tools/error_index_generator/error-index.css create mode 100644 src/tools/error_index_generator/error-index.js create mode 100644 src/tools/error_index_generator/redirect.js diff --git a/Cargo.lock b/Cargo.lock index 7c3879fdd98..8dff674a630 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1268,7 +1268,7 @@ dependencies = [ name = "error_index_generator" version = "0.0.0" dependencies = [ - "rustdoc", + "mdbook", ] [[package]] diff --git a/src/bootstrap/doc.rs b/src/bootstrap/doc.rs index 2852442d0be..f909ecc0ab8 100644 --- a/src/bootstrap/doc.rs +++ b/src/bootstrap/doc.rs @@ -793,7 +793,7 @@ impl Step for ErrorIndex { t!(fs::create_dir_all(&out)); let mut index = tool::ErrorIndex::command(builder); index.arg("html"); - index.arg(out.join("error-index.html")); + index.arg(out); index.arg(&builder.version); builder.run(&mut index); diff --git a/src/tools/error_index_generator/Cargo.toml b/src/tools/error_index_generator/Cargo.toml index b9fd852f742..f4dac6e947e 100644 --- a/src/tools/error_index_generator/Cargo.toml +++ b/src/tools/error_index_generator/Cargo.toml @@ -4,7 +4,7 @@ version = "0.0.0" edition = "2021" [dependencies] -rustdoc = { path = "../../librustdoc" } +mdbook = { version = "0.4", default-features = false, features = ["search"] } [[bin]] name = "error_index_generator" diff --git a/src/tools/error_index_generator/book_config.toml b/src/tools/error_index_generator/book_config.toml new file mode 100644 index 00000000000..885100ae3a4 --- /dev/null +++ b/src/tools/error_index_generator/book_config.toml @@ -0,0 +1,19 @@ +[book] +title = "Error codes index" +description = "Book listing all Rust error codes" +src = "" + +[output.html] +git-repository-url = "https://github.com/rust-lang/rust/" +additional-css = ["error-index.css"] +additional-js = ["error-index.js"] + +[output.html.search] +enable = true +limit-results = 20 +use-boolean-and = true +boost-title = 2 +boost-hierarchy = 2 +boost-paragraph = 1 +expand = true +heading-split-level = 0 diff --git a/src/tools/error_index_generator/error-index.css b/src/tools/error_index_generator/error-index.css new file mode 100644 index 00000000000..8975af82de0 --- /dev/null +++ b/src/tools/error_index_generator/error-index.css @@ -0,0 +1,38 @@ +code.compile_fail { + border-left: 2px solid red; +} + +pre .tooltip { + position: absolute; + left: -25px; + top: 0; + z-index: 1; + color: red; + cursor: pointer; +} +pre .tooltip::after { + display: none; + content: "This example deliberately fails to compile"; + background-color: #000; + color: #fff; + border-color: #000; + text-align: center; + padding: 5px 3px 3px 3px; + border-radius: 6px; + margin-left: 5px; +} +pre .tooltip::before { + display: none; + border-color: transparent black transparent transparent; + content: " "; + position: absolute; + top: 50%; + left: 16px; + margin-top: -5px; + border-width: 5px; + border-style: solid; +} + +pre .tooltip:hover::before, pre .tooltip:hover::after { + display: inline; +} diff --git a/src/tools/error_index_generator/error-index.js b/src/tools/error_index_generator/error-index.js new file mode 100644 index 00000000000..39b371be04b --- /dev/null +++ b/src/tools/error_index_generator/error-index.js @@ -0,0 +1,9 @@ +for (const elem of document.querySelectorAll("pre.playground")) { + if (elem.querySelector(".compile_fail") === null) { + continue; + } + const child = document.createElement("div"); + child.className = "tooltip"; + child.textContent = "ⓘ"; + elem.appendChild(child); +} diff --git a/src/tools/error_index_generator/main.rs b/src/tools/error_index_generator/main.rs index 68c46700361..5451e45b28b 100644 --- a/src/tools/error_index_generator/main.rs +++ b/src/tools/error_index_generator/main.rs @@ -1,20 +1,21 @@ #![feature(rustc_private)] extern crate rustc_driver; -extern crate rustc_span; +// We use the function we generate from `register_diagnostics!`. use crate::error_codes::error_codes; use std::env; use std::error::Error; -use std::fs::{create_dir_all, File}; +use std::fs::{self, create_dir_all, File}; use std::io::Write; use std::path::Path; use std::path::PathBuf; -use rustc_span::edition::DEFAULT_EDITION; +use std::str::FromStr; -use rustdoc::html::markdown::{ErrorCodes, HeadingOffset, IdMap, Markdown, Playground}; +use mdbook::book::{parse_summary, BookItem, Chapter}; +use mdbook::{Config, MDBook}; macro_rules! register_diagnostics { ($($error_code:ident: $message:expr,)+ ; $($undocumented:ident,)* ) => { @@ -33,104 +34,21 @@ macro_rules! register_diagnostics { mod error_codes; enum OutputFormat { - HTML(HTMLFormatter), + HTML, Markdown, Unknown(String), } impl OutputFormat { - fn from(format: &str, resource_suffix: &str) -> OutputFormat { + fn from(format: &str) -> OutputFormat { match &*format.to_lowercase() { - "html" => OutputFormat::HTML(HTMLFormatter(resource_suffix.to_owned())), + "html" => OutputFormat::HTML, "markdown" => OutputFormat::Markdown, s => OutputFormat::Unknown(s.to_owned()), } } } -struct HTMLFormatter(String); - -impl HTMLFormatter { - fn create_error_code_file( - &self, - err_code: &str, - explanation: &str, - parent_dir: &Path, - ) -> Result<(), Box> { - let mut output_file = File::create(parent_dir.join(err_code).with_extension("html"))?; - - self.header(&mut output_file, "../", "")?; - self.title(&mut output_file, &format!("Error code {}", err_code))?; - - let mut id_map = IdMap::new(); - let playground = - Playground { crate_name: None, url: String::from("https://play.rust-lang.org/") }; - write!( - output_file, - "{}", - Markdown { - content: explanation, - links: &[], - ids: &mut id_map, - error_codes: ErrorCodes::Yes, - edition: DEFAULT_EDITION, - playground: &Some(playground), - heading_offset: HeadingOffset::H1, - } - .into_string() - )?; - write!( - output_file, - "

\ - Back to list of error codes\ -

", - )?; - - self.footer(&mut output_file) - } - - fn header( - &self, - output: &mut dyn Write, - extra_path: &str, - extra: &str, - ) -> Result<(), Box> { - write!( - output, - r##" - - -Rust Compiler Error Index - - - - - -{extra} - - -"##, - suffix = self.0, - )?; - Ok(()) - } - - fn title(&self, output: &mut dyn Write, title: &str) -> Result<(), Box> { - write!(output, "

{}

\n", title)?; - Ok(()) - } - - fn footer(&self, output: &mut dyn Write) -> Result<(), Box> { - write!(output, "")?; - Ok(()) - } -} - /// Output an HTML page for the errors in `err_map` to `output_path`. fn render_markdown(output_path: &Path) -> Result<(), Box> { let mut output_file = File::create(output_path)?; @@ -147,61 +65,144 @@ fn render_markdown(output_path: &Path) -> Result<(), Box> { Ok(()) } -fn render_html(output_path: &Path, formatter: HTMLFormatter) -> Result<(), Box> { - let mut output_file = File::create(output_path)?; +fn move_folder(source: &Path, target: &Path) -> Result<(), Box> { + let entries = + fs::read_dir(source)?.map(|res| res.map(|e| e.path())).collect::, _>>()?; - let error_codes_dir = "error_codes"; - - let parent = output_path.parent().expect("There should have a parent").join(error_codes_dir); - - if !parent.exists() { - create_dir_all(&parent)?; - } - - formatter.header( - &mut output_file, - "", - &format!( - r#""# - ), - )?; - formatter.title(&mut output_file, "Rust Compiler Error Index")?; - - write!( - output_file, - "

This page lists all the error codes emitted by the Rust compiler. If you want a full \ - explanation on an error code, click on it.

\ -
    ", - )?; - for (err_code, explanation) in error_codes().iter() { - if let Some(explanation) = explanation { - write!( - output_file, - "
  • {1}
    • ", - error_codes_dir, err_code - )?; - formatter.create_error_code_file(err_code, explanation, &parent)?; + for entry in entries { + let file_name = entry.file_name().expect("file_name() failed").to_os_string(); + let output = target.join(file_name); + if entry.is_file() { + fs::rename(entry, output)?; } else { - write!(output_file, "
  • {}
    • ", err_code)?; + if !output.exists() { + create_dir_all(&output)?; + } + move_folder(&entry, &output)?; } } - write!(output_file, "
")?; - formatter.footer(&mut output_file) + + fs::remove_dir(&source)?; + + Ok(()) +} + +fn render_html(output_path: &Path) -> Result<(), Box> { + // We need to render into a temporary folder to prevent `mdbook` from removing everything + // in the output folder (including other completely unrelated things). + let tmp_output = output_path.join("tmp"); + + if !tmp_output.exists() { + create_dir_all(&tmp_output)?; + } + + render_html_inner(&tmp_output)?; + + move_folder(&tmp_output, output_path)?; + + Ok(()) +} + +// By default, mdbook doesn't consider code blocks as Rust ones contrary to rustdoc so we have +// to manually add `rust` attribute whenever needed. +fn add_rust_attribute_on_codeblock(explanation: &str) -> String { + // Very hacky way to add the rust attribute on all code blocks. + let mut skip = true; + explanation.split("\n```").fold(String::new(), |mut acc, part| { + if !acc.is_empty() { + acc.push_str("\n```"); + } + if !skip { + if let Some(attrs) = part.split('\n').next() { + if !attrs.contains("rust") + && (attrs.is_empty() + || attrs.contains("compile_fail") + || attrs.contains("ignore") + || attrs.contains("edition")) + { + if !attrs.is_empty() { + acc.push_str("rust,"); + } else { + acc.push_str("rust"); + } + } + } + } + skip = !skip; + acc.push_str(part); + acc + }) +} + +fn render_html_inner(output_path: &Path) -> Result<(), Box> { + // We need to have a little difference between `summary` and `introduction` because the "draft" + // chapters (the ones looking like `[a]()`) are not handled correctly when being put into a + // `Chapter` directly: they generate a link whereas they shouldn't. + let mut introduction = format!( + " +# Rust error codes index + +This page lists all the error codes emitted by the Rust compiler. + +", + include_str!("redirect.js") + ); + + let err_codes = error_codes(); + let mut chapters = Vec::with_capacity(err_codes.len()); + + for (err_code, explanation) in err_codes.iter() { + if let Some(explanation) = explanation { + introduction.push_str(&format!(" * [{0}](./error_codes/{0}.html)\n", err_code)); + + let content = add_rust_attribute_on_codeblock(explanation); + chapters.push(BookItem::Chapter(Chapter { + name: err_code.to_string(), + content: format!("# Error code {}\n\n{}\n", err_code, content), + number: None, + sub_items: Vec::new(), + // We generate it into the `error_codes` folder. + path: Some(PathBuf::from(&format!("error_codes/{}.html", err_code))), + source_path: None, + parent_names: Vec::new(), + })); + } else { + introduction.push_str(&format!(" * {}\n", err_code)); + } + } + + let mut config = Config::from_str(include_str!("book_config.toml"))?; + config.build.build_dir = output_path.to_path_buf(); + let mut book = MDBook::load_with_config_and_summary( + env!("CARGO_MANIFEST_DIR"), + config, + parse_summary("")?, + )?; + let chapter = Chapter { + name: "Rust error codes index".to_owned(), + content: introduction, + number: None, + sub_items: chapters, + // Very important: this file is named as `error-index.html` and not `index.html`! + path: Some(PathBuf::from("error-index.html")), + source_path: None, + parent_names: Vec::new(), + }; + book.book.sections.push(BookItem::Chapter(chapter)); + book.build()?; + + // We don't need this file since it's handled by doc.rust-lang.org directly. + let _ = fs::remove_file(output_path.join("404.html")); + // We don't want this file either because it would overwrite the already existing `index.html`. + let _ = fs::remove_file(output_path.join("index.html")); + + Ok(()) } fn main_with_result(format: OutputFormat, dst: &Path) -> Result<(), Box> { match format { OutputFormat::Unknown(s) => panic!("Unknown output format: {}", s), - OutputFormat::HTML(h) => render_html(dst, h), + OutputFormat::HTML => render_html(dst), OutputFormat::Markdown => render_markdown(dst), } } @@ -210,12 +211,9 @@ fn parse_args() -> (OutputFormat, PathBuf) { let mut args = env::args().skip(1); let format = args.next(); let dst = args.next(); - let resource_suffix = args.next().unwrap_or_else(String::new); - let format = format - .map(|a| OutputFormat::from(&a, &resource_suffix)) - .unwrap_or(OutputFormat::from("html", &resource_suffix)); + let format = format.map(|a| OutputFormat::from(&a)).unwrap_or(OutputFormat::from("html")); let dst = dst.map(PathBuf::from).unwrap_or_else(|| match format { - OutputFormat::HTML(..) => PathBuf::from("doc/error-index.html"), + OutputFormat::HTML => PathBuf::from("doc"), OutputFormat::Markdown => PathBuf::from("doc/error-index.md"), OutputFormat::Unknown(..) => PathBuf::from(""), }); @@ -225,9 +223,8 @@ fn parse_args() -> (OutputFormat, PathBuf) { fn main() { rustc_driver::init_env_logger("RUST_LOG"); let (format, dst) = parse_args(); - let result = - rustc_span::create_default_session_globals_then(move || main_with_result(format, &dst)); + let result = main_with_result(format, &dst); if let Err(e) = result { - panic!("{}", e.to_string()); + panic!("{:?}", e); } } diff --git a/src/tools/error_index_generator/redirect.js b/src/tools/error_index_generator/redirect.js new file mode 100644 index 00000000000..e6e910658e4 --- /dev/null +++ b/src/tools/error_index_generator/redirect.js @@ -0,0 +1,10 @@ +(function() {{ + if (window.location.hash) {{ + let code = window.location.hash.replace(/^#/, ''); + // We have to make sure this pattern matches to avoid inadvertently creating an + // open redirect. + if (/^E[0-9]+$/.test(code)) {{ + window.location = './error_codes/' + code + '.html'; + }} + }} +}})()