Reorganize Skylark Reference documentation.

--
MOS_MIGRATED_REVID=126081020

6 files changed, 62 insertions, 16 deletions

diff --git a/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java b/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java
index f1f710944e..610c15c6dd 100644
--- a/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java
+++ b/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java
@@ -42,6 +42,8 @@ public class DocgenConsts {
       "com/google/devtools/build/docgen/templates/skylark-library.vm";
   public static final String SKYLARK_NAV_TEMPLATE =
       "com/google/devtools/build/docgen/templates/skylark-nav.vm";
+  public static final String SKYLARK_MODULE_CATEGORY_TEMPLATE =
+      "com/google/devtools/build/docgen/templates/skylark-category.vm";
 
   public static final String VAR_LEFT_PANEL = "LEFT_PANEL";
 
diff --git a/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationCollector.java b/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationCollector.java
index 854c3ef82a..2ffb83517b 100644
--- a/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationCollector.java
+++ b/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationCollector.java
@@ -31,6 +31,7 @@ import com.google.devtools.build.lib.rules.java.JavaSkylarkApiProvider;
 import com.google.devtools.build.lib.rules.java.Jvm;
 import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable;
 import com.google.devtools.build.lib.skylarkinterface.SkylarkModule;
+import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory;
 import com.google.devtools.build.lib.skylarkinterface.SkylarkSignature;
 import com.google.devtools.build.lib.syntax.FuncallExpression;
 import com.google.devtools.build.lib.syntax.MethodLibrary;
@@ -52,8 +53,12 @@ import java.util.TreeMap;
  * A helper class that collects Skylark module documentation.
  */
 final class SkylarkDocumentationCollector {
-  @SkylarkModule(name = "globals",
-      doc = "Objects, functions and modules registered in the global environment.")
+  @SkylarkModule(
+    name = "globals",
+    title = "Globals",
+    category = SkylarkModuleCategory.TOP_LEVEL_TYPE,
+    doc = "Objects, functions and modules registered in the global environment."
+  )
   private static final class TopLevelModule {}
 
   private SkylarkDocumentationCollector() {}
diff --git a/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationProcessor.java b/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationProcessor.java
index a178f64e86..edf80dad68 100644
--- a/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationProcessor.java
+++ b/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationProcessor.java
@@ -16,10 +16,12 @@ package com.google.devtools.build.docgen;
 import com.google.devtools.build.docgen.skylark.SkylarkBuiltinMethodDoc;
 import com.google.devtools.build.docgen.skylark.SkylarkJavaMethodDoc;
 import com.google.devtools.build.docgen.skylark.SkylarkModuleDoc;
+import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory;
 
 import java.io.File;
 import java.io.IOException;
 import java.util.ArrayList;
+import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 
@@ -35,22 +37,29 @@ public final class SkylarkDocumentationProcessor {
   public static void generateDocumentation(String outputDir, String... clazz) throws IOException,
       BuildEncyclopediaDocException {
     Map<String, SkylarkModuleDoc> modules = SkylarkDocumentationCollector.collectModules(clazz);
-    List<SkylarkModuleDoc> navModules = new ArrayList<>();
 
     // Generate the top level module first in the doc
     SkylarkModuleDoc topLevelModule = modules.remove(
         SkylarkDocumentationCollector.getTopLevelModule().name());
-    topLevelModule.setTitle("Globals");
     writePage(outputDir, topLevelModule);
-    navModules.add(topLevelModule);
+
+    Map<SkylarkModuleCategory, List<SkylarkModuleDoc>> modulesByCategory = new HashMap<>();
+    for (SkylarkModuleCategory c : SkylarkModuleCategory.values()) {
+      modulesByCategory.put(c, new ArrayList<SkylarkModuleDoc>());
+    }
+
+    modulesByCategory.get(topLevelModule.getAnnotation().category()).add(topLevelModule);
 
     for (SkylarkModuleDoc module : modules.values()) {
       if (module.getAnnotation().documented()) {
         writePage(outputDir, module);
-        navModules.add(module);
+        modulesByCategory.get(module.getAnnotation().category()).add(module);
       }
     }
-    writeNavPage(outputDir, navModules);
+    writeCategoryPage(SkylarkModuleCategory.CONFIGURATION_FRAGMENT, outputDir, modulesByCategory);
+    writeCategoryPage(SkylarkModuleCategory.BUILTIN, outputDir, modulesByCategory);
+    writeCategoryPage(SkylarkModuleCategory.PROVIDER, outputDir, modulesByCategory);
+    writeNavPage(outputDir, modulesByCategory.get(SkylarkModuleCategory.TOP_LEVEL_TYPE));
   }
 
   private static void writePage(String outputDir, SkylarkModuleDoc module) throws IOException {
@@ -60,6 +69,18 @@ public final class SkylarkDocumentationProcessor {
     page.write(skylarkDocPath);
   }
 
+  private static void writeCategoryPage(
+      SkylarkModuleCategory category,
+      String outputDir,
+      Map<SkylarkModuleCategory, List<SkylarkModuleDoc>> modules) throws IOException {
+    File skylarkDocPath = new File(String.format("%s/skylark-%s.html",
+        outputDir, category.getTemplateIdentifier()));
+    Page page = TemplateEngine.newPage(DocgenConsts.SKYLARK_MODULE_CATEGORY_TEMPLATE);
+    page.add("category", category);
+    page.add("modules", modules.get(category));
+    page.write(skylarkDocPath);
+  }
+
   private static void writeNavPage(String outputDir, List<SkylarkModuleDoc> navModules)
       throws IOException {
     File navFile = new File(outputDir + "/" + "skylark-nav.html");
diff --git a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkModuleDoc.java b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkModuleDoc.java
index 0e3c42bee6..288eb4084b 100644
--- a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkModuleDoc.java
+++ b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkModuleDoc.java
@@ -34,7 +34,7 @@ public final class SkylarkModuleDoc extends SkylarkDoc {
   private final Map<String, SkylarkBuiltinMethodDoc> builtinMethodMap;
   private ArrayList<SkylarkJavaMethodDoc> javaMethods;
   private TreeMap<String, SkylarkMethodDoc> methodMap;
-  private String title;
+  private final String title;
 
   public SkylarkModuleDoc(SkylarkModule module, Class<?> classObject) {
     this.module = Preconditions.checkNotNull(
@@ -43,7 +43,11 @@ public final class SkylarkModuleDoc extends SkylarkDoc {
     this.builtinMethodMap = new TreeMap<>();
     this.methodMap = new TreeMap<>();
     this.javaMethods = new ArrayList<>();
-    this.title = module.name();
+    if (module.title().isEmpty()) {
+      this.title = module.name();
+    } else {
+      this.title = module.title();
+    }
   }
 
   @Override
@@ -60,10 +64,6 @@ public final class SkylarkModuleDoc extends SkylarkDoc {
     return title;
   }
 
-  public void setTitle(String title) {
-    this.title = title;
-  }
-
   public SkylarkModule getAnnotation() {
     return module;
   }
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/skylark-category.vm b/src/main/java/com/google/devtools/build/docgen/templates/skylark-category.vm
new file mode 100644
index 0000000000..b635e48e7d
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/docgen/templates/skylark-category.vm
@@ -0,0 +1,16 @@
+---
+layout: documentation
+title: ${category.title}
+---
+<h1>${category.title}</h1>
+
+${category.description}
+
+<div class="toc">
+<ul>
+#foreach ($module in $modules)
+
+<li><a href="/docs/skylark/lib/${module.name}.html">${module.title}</a></li>
+#end
+</ul>
+</div>
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/skylark-nav.vm b/src/main/java/com/google/devtools/build/docgen/templates/skylark-nav.vm
index 54194c0c24..46f5d1bb8d 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/skylark-nav.vm
+++ b/src/main/java/com/google/devtools/build/docgen/templates/skylark-nav.vm
@@ -1,4 +1,6 @@
-#foreach ($module in $modules)
+<li><a href="/docs/skylark/lib/skylark-builtin.html">Builtin Types and Modules</a></li>
+<li><a href="/docs/skylark/lib/skylark-configuration-fragment.html">Configuration fragments</a></li>
+<li><a href="/docs/skylark/lib/skylark-provider.html">Providers</a></li>
+<li><a href="/docs/skylark/lib/globals.html">Globals</a></li>
+<li><a href="/docs/skylark/lib/native.html">Native Module</a></li>
 
-<li><a href="/docs/skylark/lib/${module.name}.html">${module.title}</a></li>
-#end