Fix the documentation to allow making links to BE documetation articles

PiperOrigin-RevId: 178910168

6 files changed, 28 insertions, 21 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 3e8b511e32..d5e003715d 100644
--- a/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java
+++ b/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java
@@ -45,6 +45,10 @@ public class DocgenConsts {
   public static final String SKYLARK_OVERVIEW_TEMPLATE =
       "com/google/devtools/build/docgen/templates/skylark-overview.vm";
 
+  // Build Encyclopedia documentation root
+  // Can be overridden from SkylarkDocumentationProcessor#parseOptions
+  public static String BEDocsRoot = "/versions/master/be";
+
   public static final String VAR_LEFT_PANEL = "LEFT_PANEL";
 
   public static final String VAR_SECTION_BINARY = "SECTION_BINARY";
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 c38bfa2697..4dc96ebbca 100644
--- a/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationCollector.java
+++ b/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationCollector.java
@@ -68,10 +68,8 @@ final class SkylarkDocumentationCollector {
    *
    * <p>WARNING: This method no longer supports the specification of additional module classes via
    * parameters. Instead, all module classes are being picked up automatically.
-   *
-   * @param clazz DEPRECATED.
    */
-  public static Map<String, SkylarkModuleDoc> collectModules(@Deprecated String... clazz)
+  public static Map<String, SkylarkModuleDoc> collectModules()
       throws ClassPathException {
     Map<String, SkylarkModuleDoc> modules = new TreeMap<>();
     Map<SkylarkModule, Class<?>> builtinModules = new HashMap<>();
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 8cd0e17761..f6525f6849 100644
--- a/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationProcessor.java
+++ b/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationProcessor.java
@@ -30,7 +30,9 @@ import java.util.List;
 import java.util.Locale;
 import java.util.Map;
 
-/** A class to assemble documentation for Skylark. */
+/**
+ * A class to assemble documentation for Skylark.
+ */
 public final class SkylarkDocumentationProcessor {
 
   private static final ImmutableList<SkylarkModuleCategory> GLOBAL_CATEGORIES =
@@ -39,10 +41,14 @@ public final class SkylarkDocumentationProcessor {
 
   private SkylarkDocumentationProcessor() {}
 
-  /** Generates the Skylark documentation to the given output directory. */
-  public static void generateDocumentation(String outputDir, String... clazz)
+  /**
+   * Generates the Skylark documentation to the given output directory.
+   */
+  public static void generateDocumentation(String outputDir, String... args)
       throws IOException, ClassPathException {
-    Map<String, SkylarkModuleDoc> modules = SkylarkDocumentationCollector.collectModules(clazz);
+    parseOptions(args);
+
+    Map<String, SkylarkModuleDoc> modules = SkylarkDocumentationCollector.collectModules();
 
     // Generate the top level module first in the doc
     SkylarkModuleDoc topLevelModule = modules.remove(
@@ -188,7 +194,7 @@ public final class SkylarkDocumentationProcessor {
       } else {
         return getFunctionDoc(module.getAnnotation().name(), params[1], module);
       }
-    } else if (toplevelModuleDoc.getBuiltinMethods().containsKey(params[0])){
+    } else if (toplevelModuleDoc.getBuiltinMethods().containsKey(params[0])) {
       // Top level object / function
       return getFunctionDoc(null, params[0], toplevelModuleDoc);
     }
@@ -233,4 +239,12 @@ public final class SkylarkDocumentationProcessor {
     sb.append(method.getSignature())
       .append("\t").append(method.getDocumentation()).append("\n");
   }
+
+  private static void parseOptions(String... args) {
+    for (String arg : args) {
+      if (arg.startsWith("--be_root=")) {
+        DocgenConsts.BEDocsRoot = arg.split("--be_root=", 2)[1];
+      }
+    }
+  }
 }
diff --git a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkParamDoc.java b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkParamDoc.java
index 2b4be5497f..aa5d85a167 100644
--- a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkParamDoc.java
+++ b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkParamDoc.java
@@ -13,6 +13,7 @@
 // limitations under the License.
 package com.google.devtools.build.docgen.skylark;
 
+import com.google.devtools.build.docgen.DocgenConsts;
 import com.google.devtools.build.lib.skylarkinterface.Param;
 import com.google.devtools.build.lib.skylarkinterface.ParamType;
 
@@ -70,6 +71,6 @@ public final class SkylarkParamDoc extends SkylarkDoc {
 
   @Override
   public String getDocumentation() {
-    return param.doc();
+    return param.doc().replace("$BE_ROOT", DocgenConsts.BEDocsRoot);
   }
 }
diff --git a/src/main/java/com/google/devtools/build/lib/BUILD b/src/main/java/com/google/devtools/build/lib/BUILD
index 6698ed08ba..8b6647f982 100644
--- a/src/main/java/com/google/devtools/build/lib/BUILD
+++ b/src/main/java/com/google/devtools/build/lib/BUILD
@@ -1215,21 +1215,11 @@ 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 external" +
-          " ".join(SKYLARK_REPOSITORY_CLASSES) +
+          "$(location //src/main/java/com/google/devtools/build/docgen:skydoc_bin) $(@D)/skylark-lib" +
           " && zip -qj $@ $(@D)/skylark-lib/*",
     tools = ["//src/main/java/com/google/devtools/build/docgen:skydoc_bin"],
     visibility = ["//site:__pkg__"],
diff --git a/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleImplementationFunctions.java b/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleImplementationFunctions.java
index 3efcc6dc13..5a0ea681bd 100644
--- a/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleImplementationFunctions.java
+++ b/src/main/java/com/google/devtools/build/lib/analysis/skylark/SkylarkRuleImplementationFunctions.java
@@ -189,7 +189,7 @@ public class SkylarkRuleImplementationFunctions {
         positional = false,
         doc =
             "information for scheduling the action. See "
-                + "<a href=\"/docs/be/common-definitions.html#common.tags\">tags</a> "
+                + "<a href=\"$BE_ROOT/common-definitions.html#common.tags\">tags</a> "
                 + "for useful keys."
       ),
       @Param(