Small docs updates for the extra action rule.

Add the product name to the ConfiguredRuleClassProvider so that the doc
generator can generate the proper links to the user manual.

--
MOS_MIGRATED_REVID=137505460

7 files changed, 42 insertions, 7 deletions

diff --git a/src/main/java/com/google/devtools/build/docgen/BuildDocCollector.java b/src/main/java/com/google/devtools/build/docgen/BuildDocCollector.java
index 69bad6c867..31133cc605 100644
--- a/src/main/java/com/google/devtools/build/docgen/BuildDocCollector.java
+++ b/src/main/java/com/google/devtools/build/docgen/BuildDocCollector.java
@@ -160,7 +160,8 @@ public class BuildDocCollector {
    */
   public Map<String, RuleDocumentation> collect(List<String> inputDirs, String blackList)
       throws BuildEncyclopediaDocException, IOException {
-    RuleLinkExpander expander = new RuleLinkExpander(/* singlePage */ false);
+    RuleLinkExpander expander = new RuleLinkExpander(
+        ruleClassProvider.getProductName(), /* singlePage */ false);
     return collect(inputDirs, blackList, expander);
   }
 
diff --git a/src/main/java/com/google/devtools/build/docgen/MultiPageBuildEncyclopediaProcessor.java b/src/main/java/com/google/devtools/build/docgen/MultiPageBuildEncyclopediaProcessor.java
index 9c3a95153f..8ba87211a0 100644
--- a/src/main/java/com/google/devtools/build/docgen/MultiPageBuildEncyclopediaProcessor.java
+++ b/src/main/java/com/google/devtools/build/docgen/MultiPageBuildEncyclopediaProcessor.java
@@ -40,7 +40,7 @@ public class MultiPageBuildEncyclopediaProcessor extends BuildEncyclopediaProces
   public void generateDocumentation(List<String> inputDirs, String outputDir, String blackList)
       throws BuildEncyclopediaDocException, IOException {
     BuildDocCollector collector = new BuildDocCollector(ruleClassProvider, false);
-    RuleLinkExpander expander = new RuleLinkExpander(false);
+    RuleLinkExpander expander = new RuleLinkExpander(ruleClassProvider.getProductName(), false);
     Map<String, RuleDocumentation> ruleDocEntries = collector.collect(
         inputDirs, blackList, expander);
     warnAboutUndocumentedRules(
diff --git a/src/main/java/com/google/devtools/build/docgen/RuleLinkExpander.java b/src/main/java/com/google/devtools/build/docgen/RuleLinkExpander.java
index 4f74054fe1..e521c504ac 100644
--- a/src/main/java/com/google/devtools/build/docgen/RuleLinkExpander.java
+++ b/src/main/java/com/google/devtools/build/docgen/RuleLinkExpander.java
@@ -16,6 +16,7 @@ package com.google.devtools.build.docgen;
 import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.ImmutableSet;
 import java.util.HashMap;
+import java.util.Locale;
 import java.util.Map;
 import java.util.Set;
 import java.util.regex.Matcher;
@@ -51,16 +52,19 @@ public class RuleLinkExpander {
       .put("workspace", FUNCTIONS_PAGE)
       .build();
 
+  private final String productName;
   private final Map<String, String> ruleIndex = new HashMap<>();
   private final boolean singlePage;
 
-  RuleLinkExpander(Map<String, String> ruleIndex, boolean singlePage) {
+  RuleLinkExpander(String productName, Map<String, String> ruleIndex, boolean singlePage) {
+    this.productName = productName;
     this.ruleIndex.putAll(ruleIndex);
     this.ruleIndex.putAll(FUNCTIONS);
     this.singlePage = singlePage;
   }
 
-  RuleLinkExpander(boolean singlePage) {
+  RuleLinkExpander(String productName, boolean singlePage) {
+    this.productName = productName;
     this.ruleIndex.putAll(FUNCTIONS);
     this.singlePage = singlePage;
   }
@@ -182,6 +186,13 @@ public class RuleLinkExpander {
         continue;
       }
 
+      // Links to the user manual are handled specially. Meh.
+      if ("user-manual".equals(name)) {
+        String link = productName.toLowerCase(Locale.US) + "-" + name + ".html#" + heading;
+        matcher.appendReplacement(sb, Matcher.quoteReplacement(link));
+        continue;
+      }
+
       // If the reference does not match any rule or static page, throw an exception.
       throw new IllegalArgumentException(
           "Rule family " + name + " in link tag does not match any rule or BE page: "
diff --git a/src/main/java/com/google/devtools/build/docgen/SinglePageBuildEncyclopediaProcessor.java b/src/main/java/com/google/devtools/build/docgen/SinglePageBuildEncyclopediaProcessor.java
index ccacd2fbc0..56f7d29386 100644
--- a/src/main/java/com/google/devtools/build/docgen/SinglePageBuildEncyclopediaProcessor.java
+++ b/src/main/java/com/google/devtools/build/docgen/SinglePageBuildEncyclopediaProcessor.java
@@ -40,7 +40,7 @@ public class SinglePageBuildEncyclopediaProcessor extends BuildEncyclopediaProce
   public void generateDocumentation(List<String> inputDirs, String outputDir, String blackList)
       throws BuildEncyclopediaDocException, IOException {
     BuildDocCollector collector = new BuildDocCollector(ruleClassProvider, false);
-    RuleLinkExpander expander = new RuleLinkExpander(true);
+    RuleLinkExpander expander = new RuleLinkExpander(ruleClassProvider.getProductName(), true);
     Map<String, RuleDocumentation> ruleDocEntries = collector.collect(
         inputDirs, blackList, expander);
     warnAboutUndocumentedRules(
diff --git a/src/main/java/com/google/devtools/build/lib/analysis/ConfiguredRuleClassProvider.java b/src/main/java/com/google/devtools/build/lib/analysis/ConfiguredRuleClassProvider.java
index 076c5a8b7f..56c815f7b6 100644
--- a/src/main/java/com/google/devtools/build/lib/analysis/ConfiguredRuleClassProvider.java
+++ b/src/main/java/com/google/devtools/build/lib/analysis/ConfiguredRuleClassProvider.java
@@ -193,6 +193,7 @@ public class ConfiguredRuleClassProvider implements RuleClassProvider {
 
   /** Builder for {@link ConfiguredRuleClassProvider}. */
   public static class Builder implements RuleDefinitionEnvironment {
+    private String productName;
     private final StringBuilder defaultWorkspaceFilePrefix = new StringBuilder();
     private final StringBuilder defaultWorkspaceFileSuffix = new StringBuilder();
     private Label preludeLabel;
@@ -221,6 +222,11 @@ public class ConfiguredRuleClassProvider implements RuleClassProvider {
         registeredSkylarkProviders = ImmutableBiMap.builder();
     private Map<String, String> platformRegexps = new TreeMap<>();
 
+    public Builder setProductName(String productName) {
+      this.productName = productName;
+      return this;
+    }
+
     public void addWorkspaceFilePrefix(String contents) {
       defaultWorkspaceFilePrefix.append(contents);
     }
@@ -418,6 +424,7 @@ public class ConfiguredRuleClassProvider implements RuleClassProvider {
       }
 
       return new ConfiguredRuleClassProvider(
+          productName,
           preludeLabel,
           runfilesPrefix,
           toolsRepository,
@@ -474,6 +481,8 @@ public class ConfiguredRuleClassProvider implements RuleClassProvider {
     }
   });
 
+  private final String productName;
+
   /**
    * Default content that should be added at the beginning of the WORKSPACE file.
    */
@@ -544,6 +553,7 @@ public class ConfiguredRuleClassProvider implements RuleClassProvider {
       registeredSkylarkProviders;
 
   private ConfiguredRuleClassProvider(
+      String productName,
       Label preludeLabel,
       String runfilesPrefix,
       String toolsRepository,
@@ -561,6 +571,7 @@ public class ConfiguredRuleClassProvider implements RuleClassProvider {
       ImmutableMap<String, Object> skylarkAccessibleJavaClasses,
       ImmutableList<Class<?>> skylarkModules,
       ImmutableBiMap<String, Class<? extends TransitiveInfoProvider>> registeredSkylarkProviders) {
+    this.productName = productName;
     this.preludeLabel = preludeLabel;
     this.runfilesPrefix = runfilesPrefix;
     this.toolsRepository = toolsRepository;
@@ -579,6 +590,10 @@ public class ConfiguredRuleClassProvider implements RuleClassProvider {
     this.registeredSkylarkProviders = registeredSkylarkProviders;
   }
 
+  public String getProductName() {
+    return productName;
+  }
+
   public PrerequisiteValidator getPrerequisiteValidator() {
     return prerequisiteValidator;
   }
diff --git a/src/main/java/com/google/devtools/build/lib/bazel/rules/BazelRuleClassProvider.java b/src/main/java/com/google/devtools/build/lib/bazel/rules/BazelRuleClassProvider.java
index fafaf57a55..f1eb576ca0 100644
--- a/src/main/java/com/google/devtools/build/lib/bazel/rules/BazelRuleClassProvider.java
+++ b/src/main/java/com/google/devtools/build/lib/bazel/rules/BazelRuleClassProvider.java
@@ -276,6 +276,7 @@ public class BazelRuleClassProvider {
         @Override
         public void init(Builder builder) {
           builder
+              .setProductName("bazel")
               .setConfigurationCollectionFactory(new BazelConfigurationCollection())
               .setPrelude("//tools/build_rules:prelude_bazel")
               .setRunfilesPrefix(Label.DEFAULT_REPOSITORY_DIRECTORY)
diff --git a/src/main/java/com/google/devtools/build/lib/bazel/rules/common/BazelExtraActionRule.java b/src/main/java/com/google/devtools/build/lib/bazel/rules/common/BazelExtraActionRule.java
index 6849f6d4af..3db02af588 100644
--- a/src/main/java/com/google/devtools/build/lib/bazel/rules/common/BazelExtraActionRule.java
+++ b/src/main/java/com/google/devtools/build/lib/bazel/rules/common/BazelExtraActionRule.java
@@ -47,7 +47,7 @@ public final class BazelExtraActionRule implements RuleDefinition {
         <p>
           The build system ensures these prerequisites are built before running the
           <code>extra_action</code> command; they are built using the
-          <a href='../bazel-user-manual.html#configurations'><code>host</code>configuration</a>,
+          <a href='${link user-manual#configurations}'><code>host</code>configuration</a>,
           since they must run as a tool during the build itself. The path of an individual
           <code>tools</code> target <code>//x:y</code> can be obtained using
           <code>$(location //x:y)</code>.
@@ -137,7 +137,7 @@ public final class BazelExtraActionRule implements RuleDefinition {
 
 <p>
   See <a href="${link action_listener}"><code>action_listener</code></a> for details
-  on how to enable <code>extra_action</code>s in Bazel.
+  on how to enable <code>extra_action</code>s.
 </p>
 
 <p>
@@ -145,6 +145,13 @@ public final class BazelExtraActionRule implements RuleDefinition {
   access to a file containing a protocol buffer as $(EXTRA_ACTION_FILE)
   with detailed information on the original action it is shadowing.
   It also has access to all the input files the original action has access to.
+  See <tt>extra_actions.proto</tt>
+  for details on the data stored inside the protocol buffer. Each proto file
+  contains an ExtraActionInfo message.
+</p>
+
+<p>
+  Just like all other actions, extra actions are sandboxed, and should be designed to handle that.
 </p>
 
 <!-- #END_BLAZE_RULE -->*/