Improve bugpatterns list generation

moving templating into the doc gen tool, instead of dumping yaml and
letting jekyll handle it.

RELNOTES: N/A
-------------
Created by MOE: https://github.com/google/moe
MOE_MIGRATED_REVID=108302103

docgen/src/main/java/com/google/errorprone/BugPatternIndexYamlWriter.java → docgen/src/main/java/com/google/errorprone/BugPatternIndexWriter.java

@@ -24,10 +24,19 @@
 import com.google.common.collect.ListMultimap;
 import com.google.common.collect.Ordering;
 
+import com.github.mustachejava.DefaultMustacheFactory;
+import com.github.mustachejava.Mustache;
+import com.github.mustachejava.MustacheFactory;
+
+import org.yaml.snakeyaml.DumperOptions;
 import org.yaml.snakeyaml.Yaml;
 
+import java.io.IOException;
+import java.io.StringWriter;
 import java.io.Writer;
+import java.util.ArrayList;
 import java.util.Collection;
+import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.Map.Entry;
@@ -36,9 +45,11 @@
 /**
  * @author alexeagle@google.com (Alex Eagle)
  */
-public class BugPatternIndexYamlWriter {
+public class BugPatternIndexWriter {
+
+  void dump(Collection<BugPatternInstance> patterns, Writer w, boolean generateFrontMatter)
+      throws IOException {
 
-  void dump(Collection<BugPatternInstance> patterns, Writer w) {
     Map<String, List<Map<String, String>>> data = new TreeMap<>(Ordering.natural().reverse());
 
     ListMultimap<String, BugPatternInstance> index =
@@ -47,7 +58,7 @@ void dump(Collection<BugPatternInstance> patterns, Writer w) {
             new Function<BugPatternInstance, String>() {
               @Override
               public String apply(BugPatternInstance input) {
-                return input.maturity.description + " : " + input.severity;
+                return (input.maturity.description + " : " + input.severity).replace("_", "\\_");
               }
             });
 
@@ -70,6 +81,33 @@ public int compare(Map<String, String> left, Map<String, String> right) {
                     }
                   }));
     }
-    new Yaml().dump(data, w);
+
+    Map<String, Object> templateData = new HashMap<>();
+
+    if (generateFrontMatter) {
+      Map<String, String> frontmatterData =
+          ImmutableMap.<String, String>builder()
+              .put("title", "Bug Patterns")
+              .put("layout", "master")
+              .build();
+      DumperOptions options = new DumperOptions();
+      options.setDefaultFlowStyle(DumperOptions.FlowStyle.BLOCK);
+      Yaml yaml = new Yaml(options);
+      Writer yamlWriter = new StringWriter();
+      yamlWriter.write("---\n");
+      yaml.dump(frontmatterData, yamlWriter);
+      yamlWriter.write("---\n");
+      templateData.put("frontmatter", yamlWriter.toString());
+    }
+
+    List<Map<String, Object>> entryData = new ArrayList<>();
+    for (Entry<String, List<Map<String, String>>> entry : data.entrySet()) {
+      entryData.add(ImmutableMap.of("category", entry.getKey(), "checks", entry.getValue()));
+    }
+    templateData.put("bugpatterns", entryData);
+
+    MustacheFactory mf = new DefaultMustacheFactory();
+    Mustache mustache = mf.compile("com/google/errorprone/resources/bugpatterns.mustache");
+    mustache.execute(w, templateData);
   }
 }

docgen/src/main/java/com/google/errorprone/DocGenTool.java

@@ -96,9 +96,10 @@ public static void main(String[] args) throws IOException {
             explanationDir,
             options.generateFrontMatter,
             options.usePygments);
-    try (Writer w = Files.newBufferedWriter(
-        wikiDir.resolve("_data/bugpatterns.yaml"), StandardCharsets.UTF_8)) {
-      new BugPatternIndexYamlWriter().dump(readLines(bugPatterns.toFile(), UTF_8, generator), w);
+    try (Writer w =
+            Files.newBufferedWriter(wikiDir.resolve("bugpatterns.md"), StandardCharsets.UTF_8)) {
+      new BugPatternIndexWriter()
+          .dump(readLines(bugPatterns.toFile(), UTF_8, generator), w, options.generateFrontMatter);
     }
   }
 

docgen/src/main/java/com/google/errorprone/resources/bugpatterns.mustache

@@ -0,0 +1,24 @@
+{{#frontmatter}}
+{{{frontmatter}}}
+{{/frontmatter}}
+
+# Bug patterns
+
+This list is auto-generated from our sources. Each bug pattern includes code
+examples of both positive and negative cases; these examples are used in our
+regression test suite.
+
+Patterns which are marked __Experimental__ will not be evaluated against your
+code, unless you specifically configure Error Prone. The default checks are
+marked __On by default__, and each release promotes some experimental checks
+after we've vetted them against Google's codebase.
+
+{{#bugpatterns}}
+## {{category}}
+
+{{#checks}}
+__[{{name}}](bugpattern/{{name}})__\
+{{summary}}
+
+{{/checks}}
+{{/bugpatterns}}

docgen/src/test/java/com/google/errorprone/BugPatternIndexYamlWriterTest.java → docgen/src/test/java/com/google/errorprone/BugPatternIndexWriterTest.java

@@ -31,7 +31,7 @@
 import java.util.Arrays;
 
 @RunWith(JUnit4.class)
-public class BugPatternIndexYamlWriterTest {
+public class BugPatternIndexWriterTest {
   @Test
   public void dump() throws Exception {
     StringWriter writer = new StringWriter();
@@ -54,15 +54,35 @@ public void dump() throws Exception {
     pattern3.name = "BugPatternC";
     pattern3.summary = "mature";
 
-    new BugPatternIndexYamlWriter().dump(Arrays.asList(pattern3, pattern2, pattern1), writer);
+    new BugPatternIndexWriter().dump(Arrays.asList(pattern3, pattern2, pattern1), writer, false);
     assertThat(
         writer.toString(),
         is(
-            "'On by default : ERROR':\n"
-                + "- {name: BugPatternC, summary: mature}\n"
-                + "'Experimental : ERROR':\n"
-                + "- {name: BugPatternA, summary: Here's the \"interesting\" summary}\n"
-                + "- {name: BugPatternB, summary: '{summary2}'}\n"));
+            "\n"
+                + "# Bug patterns\n"
+                + "\n"
+                + "This list is auto-generated from our sources. Each bug pattern includes code\n"
+                + "examples of both positive and negative cases; these examples are used in our\n"
+                + "regression test suite.\n"
+                + "\n"
+                + "Patterns which are marked __Experimental__ will not be evaluated against your\n"
+                + "code, unless you specifically configure Error Prone. The default checks are\n"
+                + "marked __On by default__, and each release promotes some experimental checks\n"
+                + "after we've vetted them against Google's codebase.\n"
+                + "\n"
+                + "## On by default : ERROR\n"
+                + "\n"
+                + "__[BugPatternC](bugpattern/BugPatternC)__\\\n"
+                + "mature\n"
+                + "\n"
+                + "## Experimental : ERROR\n"
+                + "\n"
+                + "__[BugPatternA](bugpattern/BugPatternA)__\\\n"
+                + "Here's the "interesting" summary\n"
+                + "\n"
+                + "__[BugPatternB](bugpattern/BugPatternB)__\\\n"
+                + "{summary2}\n"
+                + "\n"));
 
   }
 }