Split Build Encyclopedia into multiple pages.

--
MOS_MIGRATED_REVID=106092764

1 files changed, 77 insertions, 89 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 9b1810dc16..66923b10a7 100644
--- a/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaProcessor.java
+++ b/src/main/java/com/google/devtools/build/docgen/BuildEncyclopediaProcessor.java
@@ -25,11 +25,13 @@ 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;
@@ -61,74 +63,45 @@ public class BuildEncyclopediaProcessor {
 
   /**
    * Collects and processes all the rule and attribute documentation in inputDirs and
-   * generates the Build Encyclopedia into the outputRootDir.
-   * 
+   * generates the Build Encyclopedia into the outputDir.
+   *
    * @param inputDirs list of directory to scan for document in the source code
    * @param outputRootDir output directory where to write the build encyclopedia
    * @param blackList optional path to a file listing rules to not document
    */
-  public void generateDocumentation(String[] inputDirs, String outputRootDir, String blackList)
+  public void generateDocumentation(String[] inputDirs, String outputDir, String blackList)
       throws BuildEncyclopediaDocException, IOException {
-    File buildEncyclopediaPath = setupDirectories(outputRootDir);
-
-    Page page = TemplateEngine.newPage(
-        "com/google/devtools/build/docgen/templates/build-encyclopedia.vm");
+    writeStaticPage(outputDir, "make-variables");
+    writeStaticPage(outputDir, "predefined-python-variables");
+    writeStaticPage(outputDir, "functions");
+    writeCommonDefinitionsPage(outputDir);
 
     BuildDocCollector collector = new BuildDocCollector(ruleClassProvider, false);
     Map<String, RuleDocumentation> ruleDocEntries = collector.collect(inputDirs, blackList);
     warnAboutUndocumentedRules(
         Sets.difference(ruleClassProvider.getRuleClassMap().keySet(), ruleDocEntries.keySet()));
-    writeRuleClassDocs(ruleDocEntries.values(), page);
-    page.write(buildEncyclopediaPath);
-  }
-
 
-  /**
-   * Categorizes, checks and prints all the rule-class documentations.
-   */
-  private void writeRuleClassDocs(Iterable<RuleDocumentation> docEntries, Page page)
-      throws BuildEncyclopediaDocException, IOException {
-    Set<RuleDocumentation> binaryDocs = new TreeSet<>();
-    Set<RuleDocumentation> libraryDocs = new TreeSet<>();
-    Set<RuleDocumentation> testDocs = new TreeSet<>();
-    Set<RuleDocumentation> otherDocs = new TreeSet<>();
-
-    for (RuleDocumentation doc : docEntries) {
-      RuleClass ruleClass = ruleClassProvider.getRuleClassMap().get(doc.getRuleName());
-      if (!ruleClass.isDocumented()) {
-        continue;
-      }
-
-      if (doc.isLanguageSpecific()) {
-        switch(doc.getRuleType()) {
-          case BINARY:
-            binaryDocs.add(doc);
-            break;
-          case LIBRARY:
-            libraryDocs.add(doc);
-            break;
-          case TEST:
-            testDocs.add(doc);
-            break;
-          case OTHER:
-            otherDocs.add(doc);
-            break;
-        }
-      } else {
-        otherDocs.add(doc);
-      }
-    }
+    writeRuleDocs(outputDir, ruleDocEntries.values());
+  }
 
-    renderBeHeader(docEntries, page);
+  private void writeStaticPage(String outputDir, String name) throws IOException {
+    File file = new File(outputDir + "/" + name + ".html");
+    Page page = TemplateEngine.newPage(
+        "com/google/devtools/build/docgen/templates/be/" + name + ".vm");
+    page.write(file);
+  }
 
-    page.add("binaryDocs", binaryDocs);
-    page.add("libraryDocs", libraryDocs);
-    page.add("testDocs", testDocs);
-    page.add("otherDocs", otherDocs);
+  private void writeCommonDefinitionsPage(String outputDir) throws IOException {
+    File file = new File(outputDir + "/common-definitions.html");
+    Page page = TemplateEngine.newPage(DocgenConsts.COMMON_DEFINITIONS_TEMPLATE);
+    page.add("commonAttributes", PredefinedAttributes.COMMON_ATTRIBUTES);
+    page.add("testAttributes", PredefinedAttributes.TEST_ATTRIBUTES);
+    page.add("binaryAttributes", PredefinedAttributes.BINARY_ATTRIBUTES);
+    page.write(file);
   }
 
-  private void renderBeHeader(Iterable<RuleDocumentation> docEntries, Page page)
-      throws BuildEncyclopediaDocException {
+  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<>();
@@ -138,26 +111,70 @@ public class BuildEncyclopediaProcessor {
     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(ruleMapping.get(ruleFamily), ruleFamily));
+          new SummaryRuleFamily(ruleTypeMap, ruleFamily, ruleFamilyId));
+      writeRuleDoc(outputDir, ruleFamily, ruleFamilyId, ruleTypeMap);
+      ruleFamilyNames.add(Pair.<String, String>of(ruleFamilyId, ruleFamily));
     }
 
     List<SummaryRuleFamily> otherSummaryFamilies =
         new ArrayList<SummaryRuleFamily>(genericRuleFamilies.size());
     for (String ruleFamily : genericRuleFamilies) {
-      otherSummaryFamilies.add(
-          new SummaryRuleFamily(ruleMapping.get(ruleFamily), ruleFamily));
+      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)
+      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("commonAttributes", PredefinedAttributes.COMMON_ATTRIBUTES);
-    page.add("testAttributes", PredefinedAttributes.TEST_ATTRIBUTES);
-    page.add("binaryAttributes", PredefinedAttributes.BINARY_ATTRIBUTES);
-    page.add(DocgenConsts.VAR_LEFT_PANEL, generateLeftNavigationPanel(docEntries));
+    page.write(file);
+  }
+
+  private void writeRuleDoc(String outputDir, String ruleFamily, String ruleFamilyId,
+      ListMultimap<RuleType, RuleDocumentation> ruleTypeMap)
+      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");
+    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 {
+    File file = new File(outputDir + "/be-nav.html");
+    Page page = TemplateEngine.newPage(DocgenConsts.BE_NAV_TEMPLATE);
+    page.add("ruleFamilyNames", ruleFamilyNames);
+    page.write(file);
   }
 
   /**
@@ -205,35 +222,6 @@ public class BuildEncyclopediaProcessor {
     }
   }
 
-  private String generateLeftNavigationPanel(Iterable<RuleDocumentation> docEntries) {
-    // Order the rules alphabetically. At this point they are ordered according to
-    // RuleDocumentation.compareTo() which is not alphabetical.
-    TreeMap<String, String> ruleNames = new TreeMap<>();
-    for (RuleDocumentation ruleDoc : docEntries) {
-      String ruleName = ruleDoc.getRuleName();
-      ruleNames.put(ruleName.toLowerCase(), ruleName);
-    }
-    StringBuilder sb = new StringBuilder();
-    for (String ruleName : ruleNames.values()) {
-      RuleClass ruleClass = ruleClassProvider.getRuleClassMap().get(ruleName);
-      Preconditions.checkNotNull(ruleClass);
-      if (ruleClass.isDocumented()) {
-        sb.append(String.format("<a href=\"#%s\">%s</a><br/>\n", ruleName, ruleName));
-      }
-    }
-    return sb.toString();
-  }
-
-  private File setupDirectories(String outputRootDir) {
-    if (outputRootDir != null) {
-      File outputRootPath = new File(outputRootDir);
-      outputRootPath.mkdirs();
-      return new File(outputRootDir + File.separator + DocgenConsts.BUILD_ENCYCLOPEDIA_NAME);
-    } else {
-      return new File(DocgenConsts.BUILD_ENCYCLOPEDIA_NAME);
-    }
-  }
-
   private static void warnAboutUndocumentedRules(Iterable<String> rulesWithoutDocumentation) {
       Iterable<String> undocumentedRules = Iterables.filter(rulesWithoutDocumentation,
           RULE_WORTH_DOCUMENTING);