Refactor BuildEncyclopediaProcessor to use a common RuleFamily class for rule

documentation passed to templates.

* This simplifies the logic in BuildEncyclopediaProcessor, reducing the number
  of various different data structures we use for generating different pages.
* This also makes RuleFamily more similar to the BuildLanguage proto, which we
  we may consider using in the future for the native rule docgen since the
  Skylark docgen will be using BuildLanguage.

--
MOS_MIGRATED_REVID=110265727

5 files changed, 86 insertions, 67 deletions

diff --git a/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaProcessor.java b/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaProcessor.java
index 66923b10a7..7c2f8f7e3f 100644
--- a/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaProcessor.java
+++ b/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaProcessor.java
@@ -25,13 +25,11 @@ import com.google.common.collect.Sets;
 import com.google.devtools.build.docgen.DocgenConsts.RuleType;
 import com.google.devtools.build.lib.analysis.ConfiguredRuleClassProvider;
 import com.google.devtools.build.lib.packages.RuleClass;
-import com.google.devtools.build.lib.util.Pair;
 
 import java.io.File;
 import java.io.IOException;
 import java.util.ArrayList;
 import java.util.HashMap;
-import java.util.LinkedList;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
@@ -100,80 +98,70 @@ public class BuildEncyclopediaProcessor {
     page.write(file);
   }
 
+  private List<RuleFamily> assembleRuleFamilies(
+      Map<String, ListMultimap<RuleType, RuleDocumentation>> ruleMapping,
+      Set<String> ruleFamilyNames) {
+    List<RuleFamily> ruleFamilies = new ArrayList<>(ruleFamilyNames.size());
+    for (String name : ruleFamilyNames) {
+      ListMultimap<RuleType, RuleDocumentation> ruleTypeMap = ruleMapping.get(name);
+      ruleFamilies.add(new RuleFamily(ruleTypeMap, name));
+    }
+    return ruleFamilies;
+  }
+
   private void writeRuleDocs(String outputDir, Iterable<RuleDocumentation> docEntries)
       throws BuildEncyclopediaDocException, IOException {
     // Separate rule families into language-specific and generic ones.
-    Set<String> languageSpecificRuleFamilies = new TreeSet<>();
-    Set<String> genericRuleFamilies = new TreeSet<>();
-    separateRuleFamilies(docEntries, languageSpecificRuleFamilies, genericRuleFamilies);
+    Set<String> langSpecificRuleFamilyNames = new TreeSet<>();
+    Set<String> genericRuleFamilyNames = new TreeSet<>();
+    separateRuleFamilies(docEntries, langSpecificRuleFamilyNames, genericRuleFamilyNames);
 
     // Create a mapping of rules based on rule type and family.
     Map<String, ListMultimap<RuleType, RuleDocumentation>> ruleMapping = new HashMap<>();
     createRuleMapping(docEntries, ruleMapping);
 
-    // Pairs of (normalized rule family name, rule family name), which used for generating
-    // the BE navigation with rule families listed in the same order as those listed in
-    // the overview table.
-    List<Pair<String, String>> ruleFamilyNames = new ArrayList<>(
-        languageSpecificRuleFamilies.size() + genericRuleFamilies.size());
-
-    List<SummaryRuleFamily> languageSpecificSummaryFamilies =
-        new ArrayList<SummaryRuleFamily>(languageSpecificRuleFamilies.size());
-    for (String ruleFamily : languageSpecificRuleFamilies) {
-      ListMultimap<RuleType, RuleDocumentation> ruleTypeMap = ruleMapping.get(ruleFamily);
-      String ruleFamilyId = RuleDocumentation.normalize(ruleFamily);
-      languageSpecificSummaryFamilies.add(
-          new SummaryRuleFamily(ruleTypeMap, ruleFamily, ruleFamilyId));
-      writeRuleDoc(outputDir, ruleFamily, ruleFamilyId, ruleTypeMap);
-      ruleFamilyNames.add(Pair.<String, String>of(ruleFamilyId, ruleFamily));
+    // Create lists of RuleFamily objects that will be used to generate the documentation.
+    // The separate language-specific and general rule families will be used to generate
+    // the Overview page while the list containing all rule families will be used to
+    // generate all other documentation.
+    List<RuleFamily> langSpecificRuleFamilies =
+        assembleRuleFamilies(ruleMapping, langSpecificRuleFamilyNames);
+    List<RuleFamily> genericRuleFamilies =
+        assembleRuleFamilies(ruleMapping, genericRuleFamilyNames);
+    List<RuleFamily> allRuleFamilies = new ArrayList<>(langSpecificRuleFamilies);
+    allRuleFamilies.addAll(genericRuleFamilies);
+
+    // Generate documentation.
+    writeOverviewPage(outputDir, langSpecificRuleFamilies, genericRuleFamilies);
+    writeBeNav(outputDir, allRuleFamilies);
+    for (RuleFamily ruleFamily : allRuleFamilies) {
+      writeRuleDoc(outputDir, ruleFamily);
     }
-
-    List<SummaryRuleFamily> otherSummaryFamilies =
-        new ArrayList<SummaryRuleFamily>(genericRuleFamilies.size());
-    for (String ruleFamily : genericRuleFamilies) {
-      ListMultimap<RuleType, RuleDocumentation> ruleTypeMap = ruleMapping.get(ruleFamily);
-      String ruleFamilyId = RuleDocumentation.normalize(ruleFamily);
-      otherSummaryFamilies.add(new SummaryRuleFamily(ruleTypeMap, ruleFamily, ruleFamilyId));
-      writeRuleDoc(outputDir, ruleFamily, ruleFamilyId, ruleTypeMap);
-      ruleFamilyNames.add(Pair.<String, String>of(ruleFamilyId, ruleFamily));
-    }
-    writeOverviewPage(outputDir, languageSpecificSummaryFamilies, otherSummaryFamilies);
-    writeBeNav(outputDir, ruleFamilyNames);
   }
 
   private void writeOverviewPage(String outputDir,
-      List<SummaryRuleFamily> languageSpecificSummaryFamilies,
-      List<SummaryRuleFamily> otherSummaryFamilies)
+      List<RuleFamily> langSpecificRuleFamilies,
+      List<RuleFamily> genericRuleFamilies)
       throws BuildEncyclopediaDocException, IOException {
     File file = new File(outputDir + "/overview.html");
     Page page = TemplateEngine.newPage(DocgenConsts.OVERVIEW_TEMPLATE);
-    page.add("langSpecificSummaryFamilies", languageSpecificSummaryFamilies);
-    page.add("otherSummaryFamilies", otherSummaryFamilies);
+    page.add("langSpecificRuleFamilies", langSpecificRuleFamilies);
+    page.add("genericRuleFamilies", genericRuleFamilies);
     page.write(file);
   }
 
-  private void writeRuleDoc(String outputDir, String ruleFamily, String ruleFamilyId,
-      ListMultimap<RuleType, RuleDocumentation> ruleTypeMap)
+  private void writeRuleDoc(String outputDir, RuleFamily ruleFamily)
       throws BuildEncyclopediaDocException, IOException {
-    List<RuleDocumentation> rules = new LinkedList<>();
-    rules.addAll(ruleTypeMap.get(RuleType.BINARY));
-    rules.addAll(ruleTypeMap.get(RuleType.LIBRARY));
-    rules.addAll(ruleTypeMap.get(RuleType.TEST));
-    rules.addAll(ruleTypeMap.get(RuleType.OTHER));
-
-    File file = new File(outputDir + "/" + ruleFamilyId + ".html");
+    File file = new File(outputDir + "/" + ruleFamily.getId() + ".html");
     Page page = TemplateEngine.newPage(DocgenConsts.RULES_TEMPLATE);
     page.add("ruleFamily", ruleFamily);
-    page.add("ruleFamilyId", ruleFamilyId);
-    page.add("ruleDocs", rules);
     page.write(file);
   }
 
-  private void writeBeNav(String outputDir, List<Pair<String, String>> ruleFamilyNames)
-      throws IOException {
+  private void writeBeNav(String outputDir, List<RuleFamily> ruleFamilies) throws IOException {
     File file = new File(outputDir + "/be-nav.html");
     Page page = TemplateEngine.newPage(DocgenConsts.BE_NAV_TEMPLATE);
-    page.add("ruleFamilyNames", ruleFamilyNames);
+    page.add("ruleFamilies", ruleFamilies);
     page.write(file);
   }
 
@@ -203,21 +191,21 @@ public class BuildEncyclopediaProcessor {
    * Separates all rule families in docEntries into language-specific rules and generic rules.
    */
   private void separateRuleFamilies(Iterable<RuleDocumentation> docEntries,
-      Set<String> languageSpecificRuleFamilies, Set<String> genericRuleFamilies)
+      Set<String> langSpecific, Set<String> generic)
       throws BuildEncyclopediaDocException {
     for (RuleDocumentation ruleDoc : docEntries) {
       if (ruleDoc.isLanguageSpecific()) {
-        if (genericRuleFamilies.contains(ruleDoc.getRuleFamily())) {
+        if (generic.contains(ruleDoc.getRuleFamily())) {
           throw ruleDoc.createException("The rule is marked as being language-specific, but other "
               + "rules of the same family have already been marked as being not.");
         }
-        languageSpecificRuleFamilies.add(ruleDoc.getRuleFamily());
+        langSpecific.add(ruleDoc.getRuleFamily());
       } else {
-        if (languageSpecificRuleFamilies.contains(ruleDoc.getRuleFamily())) {
+        if (langSpecific.contains(ruleDoc.getRuleFamily())) {
           throw ruleDoc.createException("The rule is marked as being generic, but other rules of "
               + "the same family have already been marked as being language-specific.");
         }
-        genericRuleFamilies.add(ruleDoc.getRuleFamily());
+        generic.add(ruleDoc.getRuleFamily());
       }
     }
   }
diff --git a/src/main/java/com/google/devtools/build/docgen/SummaryRuleFamily.java b/src/main/java/com/google/devtools/build/docgen/RuleFamily.java
index c55f146ae3..4c2f346d47 100644
--- a/src/main/java/com/google/devtools/build/docgen/SummaryRuleFamily.java
+++ b/src/main/java/com/google/devtools/build/docgen/RuleFamily.java
@@ -16,6 +16,8 @@ package com.google.devtools.build.docgen;
 
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.ListMultimap;
+import com.google.common.escape.CharEscaperBuilder;
+import com.google.common.escape.Escaper;
 import com.google.devtools.build.docgen.DocgenConsts.RuleType;
 import com.google.devtools.build.lib.concurrent.ThreadSafety.Immutable;
 
@@ -28,19 +30,27 @@ import java.util.List;
  * other.
  */
 @Immutable
-public class SummaryRuleFamily {
+public class RuleFamily {
+  private static final Escaper FAMILY_NAME_ESCAPER = new CharEscaperBuilder()
+      .addEscape('+', "p")
+      .addEscapes(new char[] {'[', ']', '(', ')'}, "")
+      .addEscapes(new char[] {' ', '/'}, "-")
+      .toEscaper();
+
   private final String name;
   private final String id;
+
   private final ImmutableList<RuleDocumentation> binaryRules;
   private final ImmutableList<RuleDocumentation> libraryRules;
   private final ImmutableList<RuleDocumentation> testRules;
   private final ImmutableList<RuleDocumentation> otherRules1;
   private final ImmutableList<RuleDocumentation> otherRules2;
 
-  SummaryRuleFamily(ListMultimap<RuleType, RuleDocumentation> ruleTypeMap,
-      String name, String id) {
+  private final ImmutableList<RuleDocumentation> rules;
+
+  RuleFamily(ListMultimap<RuleType, RuleDocumentation> ruleTypeMap, String name) {
     this.name = name;
-    this.id = id;
+    this.id = normalize(name);
     this.binaryRules = ImmutableList.copyOf(ruleTypeMap.get(RuleType.BINARY));
     this.libraryRules = ImmutableList.copyOf(ruleTypeMap.get(RuleType.LIBRARY));
     this.testRules = ImmutableList.copyOf(ruleTypeMap.get(RuleType.TEST));
@@ -55,6 +65,23 @@ public class SummaryRuleFamily {
       this.otherRules1 = otherRules;
       this.otherRules2 = ImmutableList.of();
     }
+
+    rules = ImmutableList.<RuleDocumentation>builder()
+        .addAll(binaryRules)
+        .addAll(libraryRules)
+        .addAll(testRules)
+        .addAll(otherRules1)
+        .addAll(otherRules2)
+        .build();
+  }
+
+  /*
+   * Returns a "normalized" version of the input string. Used to convert rule family names into
+   * strings that are more friendly as file names. For example, "C / C++" is converted to
+   * "c-cpp".
+   */
+  static String normalize(String s) {
+    return FAMILY_NAME_ESCAPER.escape(s.toLowerCase()).replaceAll("[-]+", "-");
   }
 
   public String getName() {
@@ -84,4 +111,8 @@ public class SummaryRuleFamily {
   public List<RuleDocumentation> getOtherRules2() {
     return otherRules2;
   }
+
+  public List<RuleDocumentation> getRules() {
+    return rules;
+  }
 }
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/be/be-nav.vm b/src/main/java/com/google/devtools/build/docgen/templates/be/be-nav.vm
index 10753c3f8e..44b05953c5 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/be/be-nav.vm
+++ b/src/main/java/com/google/devtools/build/docgen/templates/be/be-nav.vm
@@ -16,9 +16,9 @@
   </li>
   <li class="sidebar-nav-heading">Built-in Rules</li>
   <li><a href="${path}/functions.html">Functions</a></li>
-  #foreach ($namePair in $ruleFamilyNames)
-  <li><a href="${path}/${namePair.getFirst()}.html">${namePair.getSecond()}</a></li>
-  #end
+#foreach ($ruleFamily in $ruleFamilies)
+  <li><a href="${path}/${ruleFamily.id}.html">${ruleFamily.name}</a></li>
+#end
 
   <li class="sidebar-nav-heading">Skylark Rules</li>
   <li><a href="${path}/appengine.html">Java AppEngine</a></li>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/be/overview.vm b/src/main/java/com/google/devtools/build/docgen/templates/be/overview.vm
index 9e052c5553..38aeeb72c8 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/be/overview.vm
+++ b/src/main/java/com/google/devtools/build/docgen/templates/be/overview.vm
@@ -110,14 +110,14 @@
       <th></th>
     </tr>
   </thead>
-#summaryTable($langSpecificSummaryFamilies)
+#summaryTable($langSpecificRuleFamilies)
 
 </table>
 <h4>Rules that do not apply to a specific programming language</h4>
 
 <table class="table table-condensed table-striped" summary="Table of rules not specific to a programming language">
   <colgroup span="6" width="20%"></colgroup>
-#summaryTable($otherSummaryFamilies)
+#summaryTable($genericRuleFamilies)
 
 </table>
 #parse("com/google/devtools/build/docgen/templates/be/footer.vm")
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm b/src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm
index 4e5f6d3fc4..fc54f25f4b 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm
+++ b/src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm
@@ -1,11 +1,11 @@
 #parse("com/google/devtools/build/docgen/templates/be/header.vm")
 
-<h1>${ruleFamily} Rules</h1>
+<h1>${ruleFamily.name} Rules</h1>
 
 <div class="toc">
   <h2>Rules</h2>
   <ul>
-#foreach ($rule in $ruleDocs)
+#foreach ($rule in $ruleFamily.rules)
     <li>
       <a href="#${rule.ruleName}">
         ${rule.ruleName}#if($rule.isDeprecated()) (deprecated)#end
@@ -15,7 +15,7 @@
   </ul>
 </div>
 
-#foreach ($rule in $ruleDocs)
+#foreach ($rule in $ruleFamily.rules)
   <h2 id="${rule.ruleName}"#if($rule.isDeprecated()) class="deprecated"#end>
     ${rule.ruleName}
   </h2>