Auto merge of #25062 - michaelsproul:html-error-index, r=alexcrichton

This PR adds a program which uses the JSON output from #24884 to generate a webpage with descriptions of each diagnostic error.

The page is constructed by hand, with calls to `rustdoc`'s markdown renderers where needed. I opted to generate HTML directly as I think it's more flexible than generating a markdown file and feeding it into the `rustdoc` executable. I envision adding the ability to filter errors by their properties (description, no description, used, unused), which is infeasible using the whole-file markdown approach due to the need to wrap each error in a `<div>` (markdown inside tags isn't rendered).

Architecturally, I wasn't sure how to add this generator to the distribution. For the moment I've settled on a separate Rust program in `src/etc/` that gets compiled and run by a custom makefile rule. This approach doesn't seem too hackish, but I'm unsure if my usage of makefile variables is correct, particularly the call to `rustc` (and the `LD_LIBRARY_PATH` weirdness). Other options I considered were:

* Integrate the error-index generator into `rustdoc` so that it gets invoked via a flag and can be built as part of `rustdoc`.
* Add the error-index-generator as a "tool" to the `TOOLS` array, and make use of the facilities for building tools. The main reason I didn't do this was because it seemed like I'd need to add lots of stuff. I'm happy to investigate this further if it's the preferred method.

Author: bors

mk/crates.mk

@@ -58,7 +58,7 @@ RUSTC_CRATES := rustc rustc_typeck rustc_borrowck rustc_resolve rustc_driver \
                 rustc_data_structures
 HOST_CRATES := syntax $(RUSTC_CRATES) rustdoc fmt_macros
 CRATES := $(TARGET_CRATES) $(HOST_CRATES)
-TOOLS := compiletest rustdoc rustc rustbook
+TOOLS := compiletest rustdoc rustc rustbook error-index-generator
 
 DEPS_core :=
 DEPS_libc := core
@@ -107,10 +107,12 @@ TOOL_DEPS_compiletest := test getopts
 TOOL_DEPS_rustdoc := rustdoc
 TOOL_DEPS_rustc := rustc_driver
 TOOL_DEPS_rustbook := std rustdoc
+TOOL_DEPS_error-index-generator := rustdoc syntax serialize
 TOOL_SOURCE_compiletest := $(S)src/compiletest/compiletest.rs
 TOOL_SOURCE_rustdoc := $(S)src/driver/driver.rs
 TOOL_SOURCE_rustc := $(S)src/driver/driver.rs
 TOOL_SOURCE_rustbook := $(S)src/rustbook/main.rs
+TOOL_SOURCE_error-index-generator := $(S)src/error-index-generator/main.rs
 
 ONLY_RLIB_core := 1
 ONLY_RLIB_libc := 1

mk/docs.mk

@@ -71,9 +71,13 @@ RUSTBOOK_EXE = $(HBIN2_H_$(CFG_BUILD))/rustbook$(X_$(CFG_BUILD))
 # ./configure
 RUSTBOOK = $(RPATH_VAR2_T_$(CFG_BUILD)_H_$(CFG_BUILD)) $(RUSTBOOK_EXE)
 
+# The error-index-generator executable...
+ERR_IDX_GEN_EXE = $(HBIN2_H_$(CFG_BUILD))/error-index-generator$(X_$(CFG_BUILD))
+ERR_IDX_GEN = $(RPATH_VAR2_T_$(CFG_BUILD)_H_$(CFG_BUILD)) $(ERR_IDX_GEN_EXE)
+
 D := $(S)src/doc
 
-DOC_TARGETS := trpl style
+DOC_TARGETS := trpl style error-index
 COMPILER_DOC_TARGETS :=
 DOC_L10N_TARGETS :=
 
@@ -288,3 +292,9 @@ doc/style/index.html: $(RUSTBOOK_EXE) $(wildcard $(S)/src/doc/style/*.md) | doc/
 	@$(call E, rustbook: $@)
 	$(Q)rm -rf doc/style
 	$(Q)$(RUSTBOOK) build $(S)src/doc/style doc/style
+
+error-index: doc/error-index.html
+
+doc/error-index.html: $(ERR_IDX_GEN_EXE) | doc/
+	$(Q)$(call E, error-index-generator: $@)
+	$(Q)$(ERR_IDX_GEN)

mk/prepare.mk

@@ -70,7 +70,7 @@ define PREPARE_MAN
 	$(Q)$(PREPARE_MAN_CMD) $(PREPARE_SOURCE_MAN_DIR)/$(1) $(PREPARE_DEST_MAN_DIR)/$(1)
 endef
 
-PREPARE_TOOLS = $(filter-out compiletest rustbook, $(TOOLS))
+PREPARE_TOOLS = $(filter-out compiletest rustbook error-index-generator, $(TOOLS))
 
 
 # $(1) is tool

src/error-index-generator/main.rs

@@ -0,0 +1,119 @@
+// Copyright 2015 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+#![feature(rustc_private, rustdoc)]
+
+extern crate syntax;
+extern crate rustdoc;
+extern crate serialize as rustc_serialize;
+
+use std::collections::BTreeMap;
+use std::fs::{read_dir, File};
+use std::io::{Read, Write};
+use std::path::Path;
+use std::error::Error;
+
+use syntax::diagnostics::metadata::{get_metadata_dir, ErrorMetadataMap};
+
+use rustdoc::html::markdown::Markdown;
+use rustc_serialize::json;
+
+/// Load all the metadata files from `metadata_dir` into an in-memory map.
+fn load_all_errors(metadata_dir: &Path) -> Result<ErrorMetadataMap, Box<Error>> {
+    let mut all_errors = BTreeMap::new();
+
+    for entry in try!(read_dir(metadata_dir)) {
+        let path = try!(entry).path();
+
+        let mut metadata_str = String::new();
+        try!(
+            File::open(&path).and_then(|mut f|
+            f.read_to_string(&mut metadata_str))
+        );
+
+        let some_errors: ErrorMetadataMap = try!(json::decode(&metadata_str));
+
+        for (err_code, info) in some_errors {
+            all_errors.insert(err_code, info);
+        }
+    }
+
+    Ok(all_errors)
+}
+
+/// Output an HTML page for the errors in `err_map` to `output_path`.
+fn render_error_page(err_map: &ErrorMetadataMap, output_path: &Path) -> Result<(), Box<Error>> {
+    let mut output_file = try!(File::create(output_path));
+
+    try!(write!(&mut output_file,
+r##"<!DOCTYPE html>
+<html>
+<head>
+<title>Rust Compiler Error Index</title>
+<meta charset="utf-8">
+<!-- Include rust.css after main.css so its rules take priority. -->
+<link rel="stylesheet" type="text/css" href="main.css"/>
+<link rel="stylesheet" type="text/css" href="rust.css"/>
+<style>
+.error-undescribed {{
+    display: none;
+}}
+</style>
+</head>
+<body>
+"##
+    ));
+
+    try!(write!(&mut output_file, "<h1>Rust Compiler Error Index</h1>\n"));
+
+    for (err_code, info) in err_map.iter() {
+        // Enclose each error in a div so they can be shown/hidden en masse.
+        let desc_desc = match info.description {
+            Some(_) => "error-described",
+            None => "error-undescribed"
+        };
+        let use_desc = match info.use_site {
+            Some(_) => "error-used",
+            None => "error-unused"
+        };
+        try!(write!(&mut output_file, "<div class=\"{} {}\">", desc_desc, use_desc));
+
+        // Error title (with self-link).
+        try!(write!(&mut output_file,
+            "<h2 id=\"{0}\" class=\"section-header\"><a href=\"#{0}\">{0}</a></h2>\n",
+            err_code
+        ));
+
+        // Description rendered as markdown.
+        match info.description {
+            Some(ref desc) => try!(write!(&mut output_file, "{}", Markdown(desc))),
+            None => try!(write!(&mut output_file, "<p>No description.</p>\n"))
+        }
+
+        try!(write!(&mut output_file, "</div>\n"));
+    }
+
+    try!(write!(&mut output_file, "</body>\n</html>"));
+
+    Ok(())
+}
+
+fn main_with_result() -> Result<(), Box<Error>> {
+    let metadata_dir = get_metadata_dir();
+    let err_map = try!(load_all_errors(&metadata_dir));
+    try!(render_error_page(&err_map, Path::new("doc/error-index.html")));
+    Ok(())
+}
+
+fn main() {
+    if let Err(e) = main_with_result() {
+        panic!("{}", e.description());
+    }
+}