Adds Skylark Remote Repository documentation

Fixes #1043

--
MOS_MIGRATED_REVID=118039426

6 files changed, 45 insertions, 14 deletions

diff --git a/src/main/java/com/google/devtools/build/docgen/BUILD b/src/main/java/com/google/devtools/build/docgen/BUILD
index 0b1e0a78ff..f7248fe682 100644
--- a/src/main/java/com/google/devtools/build/docgen/BUILD
+++ b/src/main/java/com/google/devtools/build/docgen/BUILD
@@ -39,6 +39,7 @@ java_binary(
     name = "skydoc_bin",
     srcs = ["SkylarkDocumentationGenerator.java"],
     main_class = "com.google.devtools.build.docgen.SkylarkDocumentationGenerator",
+    runtime_deps = ["//src/main/java/com/google/devtools/build/lib:bazel-repository"],
     deps = [":docgen_javalib"],
 )
 
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 20a79ccd6b..854c3ef82a 100644
--- a/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationCollector.java
+++ b/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationCollector.java
@@ -69,10 +69,10 @@ final class SkylarkDocumentationCollector {
    * Collects the documentation for all Skylark modules and returns a map that maps Skylark
    * module name to the module documentation.
    */
-  public static Map<String, SkylarkModuleDoc> collectModules() {
+  public static Map<String, SkylarkModuleDoc> collectModules(String... clazz) {
     Map<String, SkylarkModuleDoc> modules = new TreeMap<>();
-    Map<String, SkylarkModuleDoc> builtinModules = collectBuiltinModules();
-    Map<SkylarkModule, Class<?>> builtinJavaObjects = collectBuiltinJavaObjects();
+    Map<String, SkylarkModuleDoc> builtinModules = collectBuiltinModules(clazz);
+    Map<SkylarkModule, Class<?>> builtinJavaObjects = collectBuiltinJavaObjects(clazz);
 
     modules.putAll(builtinModules);
     for (SkylarkModuleDoc builtinObject : builtinModules.values()) {
@@ -137,13 +137,21 @@ final class SkylarkDocumentationCollector {
     }
   }
 
-  private static Map<String, SkylarkModuleDoc> collectBuiltinModules() {
+  private static Map<String, SkylarkModuleDoc> collectBuiltinModules(String... clazz) {
     Map<String, SkylarkModuleDoc> modules = new HashMap<>();
     collectBuiltinDoc(modules, Runtime.class.getDeclaredFields());
     collectBuiltinDoc(modules, MethodLibrary.class.getDeclaredFields());
     for (Class<?> moduleClass : SkylarkModules.MODULES) {
       collectBuiltinDoc(modules, moduleClass.getDeclaredFields());
     }
+    for (String c : clazz) {
+      try {
+        collectBuiltinDoc(modules,
+            SkylarkDocumentationCollector.class.getClassLoader().loadClass(c).getDeclaredFields());
+      } catch (ClassNotFoundException e) {
+        System.err.println("SkylarkModule class " + c + " could not be found, ignoring...");
+      }
+    }
     return modules;
   }
 
@@ -171,7 +179,7 @@ final class SkylarkDocumentationCollector {
     }
   }
 
-  private static Map<SkylarkModule, Class<?>> collectBuiltinJavaObjects() {
+  private static Map<SkylarkModule, Class<?>> collectBuiltinJavaObjects(String ...clazz) {
     Map<SkylarkModule, Class<?>> modules = new HashMap<>();
     collectBuiltinModule(modules, SkylarkRuleContext.class);
     collectBuiltinModule(modules, TransitiveInfoCollection.class);
@@ -183,6 +191,14 @@ final class SkylarkDocumentationCollector {
     collectBuiltinModule(modules, JavaSkylarkApiProvider.class);
     collectBuiltinModule(modules, JavaRuleOutputJarsProvider.OutputJar.class);
     collectBuiltinModule(modules, AndroidSkylarkApiProvider.class);
+    for (String c : clazz) {
+      try {
+        collectBuiltinModule(modules,
+            SkylarkDocumentationCollector.class.getClassLoader().loadClass(c));
+      } catch (ClassNotFoundException e) {
+        System.err.println("SkylarkModule class " + c + " could not be found, ignoring...");
+      }
+    }
     return modules;
   }
 
diff --git a/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationGenerator.java b/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationGenerator.java
index 4fec2f030f..9b09c838cc 100644
--- a/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationGenerator.java
+++ b/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationGenerator.java
@@ -14,6 +14,8 @@
 package com.google.devtools.build.docgen;
 
 
+import java.util.Arrays;
+
 /**
  * The main class for the skylark documentation generator.
  */
@@ -21,7 +23,7 @@ public class SkylarkDocumentationGenerator {
 
   private static boolean checkArgs(String[] args) {
     if (args.length < 1) {
-      System.err.println("There has to be one input parameter\n"
+      System.err.println("There has to be at least one input parameter\n"
           + " - an output file.");
       return false;
     }
@@ -40,7 +42,9 @@ public class SkylarkDocumentationGenerator {
     if (checkArgs(args)) {
       System.out.println("Generating Skylark documentation...");
       try {
-        SkylarkDocumentationProcessor.generateDocumentation(args[0]);
+        SkylarkDocumentationProcessor.generateDocumentation(
+            args[0],
+            Arrays.copyOfRange(args, 1, args.length));
       } catch (Throwable e) {
         fail(e, true);
       }
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 2ed25ff353..a178f64e86 100644
--- a/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationProcessor.java
+++ b/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationProcessor.java
@@ -32,9 +32,9 @@ public final class SkylarkDocumentationProcessor {
   /**
    * Generates the Skylark documentation to the given output directory.
    */
-  public static void generateDocumentation(String outputDir) throws IOException,
+  public static void generateDocumentation(String outputDir, String... clazz) throws IOException,
       BuildEncyclopediaDocException {
-    Map<String, SkylarkModuleDoc> modules = SkylarkDocumentationCollector.collectModules();
+    Map<String, SkylarkModuleDoc> modules = SkylarkDocumentationCollector.collectModules(clazz);
     List<SkylarkModuleDoc> navModules = new ArrayList<>();
 
     // Generate the top level module first in the doc
diff --git a/src/main/java/com/google/devtools/build/lib/BUILD b/src/main/java/com/google/devtools/build/lib/BUILD
index 587e7985b3..d3e5325d67 100644
--- a/src/main/java/com/google/devtools/build/lib/BUILD
+++ b/src/main/java/com/google/devtools/build/lib/BUILD
@@ -958,12 +958,22 @@ genrule(
     ],
 )
 
+# The skylark repository classes are passed as parameter of the Skylark documentation generator.
+SKYLARK_REPOSITORY_CLASSES = [
+    "com.google.devtools.build.lib.bazel.repository.skylark.SkylarkExecutionResult",
+    "com.google.devtools.build.lib.bazel.repository.skylark.SkylarkOS",
+    "com.google.devtools.build.lib.bazel.repository.skylark.SkylarkPath",
+    "com.google.devtools.build.lib.bazel.repository.skylark.SkylarkRepositoryContext",
+    "com.google.devtools.build.lib.bazel.repository.skylark.SkylarkRepositoryModule",
+]
+
 genrule(
     name = "gen_skylarklibrary",
     outs = ["skylark-library.zip"],
     cmd = "mkdir -p $(@D)/skylark-lib &&" +
-          "$(location //src/main/java/com/google/devtools/build/docgen:skydoc_bin) $(@D)/skylark-lib &&" +
-          "zip -qj $@ $(@D)/skylark-lib/*",
+          "$(location //src/main/java/com/google/devtools/build/docgen:skydoc_bin) $(@D)/skylark-lib " +
+          " ".join(SKYLARK_REPOSITORY_CLASSES) +
+          " && zip -qj $@ $(@D)/skylark-lib/*",
     tools = ["//src/main/java/com/google/devtools/build/docgen:skydoc_bin"],
 )
 
diff --git a/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkRepositoryModule.java b/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkRepositoryModule.java
index 3332accfb8..6e82e1455f 100644
--- a/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkRepositoryModule.java
+++ b/src/main/java/com/google/devtools/build/lib/bazel/repository/skylark/SkylarkRepositoryModule.java
@@ -60,8 +60,8 @@ public class SkylarkRepositoryModule {
         type = BaseFunction.class,
         doc =
             "the function implementing this rule, has to have exactly one parameter: "
-                + "<code>repository_ctx</code>. The function is called during analysis phase for "
-                + "each instance of the rule."
+                + "<code><a href=\"repository_ctx.html\">repository_ctx</a></code>. The function "
+                + "is called during loading phase for each instance of the rule."
       )
     },
     optionalNamedOnly = {
@@ -72,7 +72,7 @@ public class SkylarkRepositoryModule {
         defaultValue = "None",
         doc =
             "dictionary to declare all the attributes of the rule. It maps from an attribute "
-                + "name to an attribute object (see <a href=\"#modules.attr\">attr</a> "
+                + "name to an attribute object (see <a href=\"attr.html\">attr</a> "
                 + "module). Attributes starting with <code>_</code> are private, and can be "
                 + "used to add an implicit dependency on a label to a file (a repository "
                 + "rule cannot depend on a generated artifact). The attribute "