Implement generating single-page Build Encyclopedia.

* Adds a --single_page flag to the BE docgen for generating a single-page
  version of the Build Encyclopedia.
* Refactor BuildEncyclopediaProcessor common logic into a base class and add
  subclasses for generating single- and multi-page BE respectively.
* Enable RuleLinkExpander to expand rule references to single-page hrefs
  (headings on the current page).
* Update docgen velocity templates to use RuleLinkExpander to ensure links are
  correct on both single- and multi-page versions of the BE.

--
MOS_MIGRATED_REVID=131574793

1 files changed, 80 insertions, 35 deletions

diff --git a/src/test/java/com/google/devtools/build/docgen/RuleLinkExpanderTest.java b/src/test/java/com/google/devtools/build/docgen/RuleLinkExpanderTest.java
index ed08c34b0a..fbacd0c080 100644
--- a/src/test/java/com/google/devtools/build/docgen/RuleLinkExpanderTest.java
+++ b/src/test/java/com/google/devtools/build/docgen/RuleLinkExpanderTest.java
@@ -16,7 +16,7 @@ package com.google.devtools.build.docgen;
 import static org.junit.Assert.assertEquals;
 
 import com.google.common.collect.ImmutableMap;
-
+import java.util.Map;
 import org.junit.Before;
 import org.junit.Test;
 import org.junit.runner.RunWith;
@@ -25,83 +25,128 @@ import org.junit.runners.JUnit4;
 /** Unit tests for {@link RuleLinkExpander}. */
 @RunWith(JUnit4.class)
 public class RuleLinkExpanderTest {
-  private RuleLinkExpander expander;
+  private RuleLinkExpander multiPageExpander;
+  private RuleLinkExpander singlePageExpander;
 
   @Before public void setUp() {
-    expander = new RuleLinkExpander(ImmutableMap.<String, String>builder()
+    Map<String, String> index = ImmutableMap.<String, String>builder()
         .put("cc_library", "c-cpp")
         .put("cc_binary", "c-cpp")
         .put("java_binary", "java")
         .put("Fileset", "fileset")
         .put("proto_library", "protocol-buffer")
-        .build());
+        .build();
+    multiPageExpander = new RuleLinkExpander(index, false);
+    singlePageExpander = new RuleLinkExpander(index, true);
+  }
+
+  private void checkExpandSingle(String docs, String expected) {
+    assertEquals(expected, singlePageExpander.expand(docs));
+  }
+
+  private void checkExpandMulti(String docs, String expected) {
+    assertEquals(expected, multiPageExpander.expand(docs));
   }
 
   @Test public void testRule() {
-    String docs = "<a href=\"${link java_binary}\">java_binary rule</a>";
-    String expected = "<a href=\"java.html#java_binary\">java_binary rule</a>";
-    assertEquals(expected, expander.expand(docs));
+    checkExpandMulti(
+        "<a href=\"${link java_binary}\">java_binary rule</a>",
+        "<a href=\"java.html#java_binary\">java_binary rule</a>");
+    checkExpandSingle(
+        "<a href=\"${link java_binary}\">java_binary rule</a>",
+        "<a href=\"#java_binary\">java_binary rule</a>");
   }
 
   @Test public void testRuleAndAttribute() {
-    String docs = "<a href=\"${link java_binary.runtime_deps}\">runtime_deps attribute</a>";
-    String expected = "<a href=\"java.html#java_binary.runtime_deps\">runtime_deps attribute</a>";
-    assertEquals(expected, expander.expand(docs));
+    checkExpandMulti(
+        "<a href=\"${link java_binary.runtime_deps}\">runtime_deps attribute</a>",
+        "<a href=\"java.html#java_binary.runtime_deps\">runtime_deps attribute</a>");
+    checkExpandSingle(
+        "<a href=\"${link java_binary.runtime_deps}\">runtime_deps attribute</a>",
+        "<a href=\"#java_binary.runtime_deps\">runtime_deps attribute</a>");
   }
 
   @Test public void testUpperCaseRule() {
-    String docs = "<a href=\"${link Fileset.entries}\">entries</a>";
-    String expected = "<a href=\"fileset.html#Fileset.entries\">entries</a>";
-    assertEquals(expected, expander.expand(docs));
+    checkExpandMulti(
+        "<a href=\"${link Fileset.entries}\">entries</a>",
+        "<a href=\"fileset.html#Fileset.entries\">entries</a>");
+    checkExpandSingle(
+        "<a href=\"${link Fileset.entries}\">entries</a>",
+        "<a href=\"#Fileset.entries\">entries</a>");
   }
 
   @Test public void testRuleExamples() {
-    String docs = "<a href=\"${link cc_binary_examples}\">examples</a>";
-    String expected = "<a href=\"c-cpp.html#cc_binary_examples\">examples</a>";
-    assertEquals(expected, expander.expand(docs));
+    checkExpandMulti(
+        "<a href=\"${link cc_binary_examples}\">examples</a>",
+        "<a href=\"c-cpp.html#cc_binary_examples\">examples</a>");
+    checkExpandSingle(
+        "<a href=\"${link cc_binary_examples}\">examples</a>",
+        "<a href=\"#cc_binary_examples\">examples</a>");
   }
 
   @Test public void testRuleArgs() {
-    String docs = "<a href=\"${link cc_binary_args}\">args</a>";
-    String expected = "<a href=\"c-cpp.html#cc_binary_args\">args</a>";
-    assertEquals(expected, expander.expand(docs));
+    checkExpandMulti(
+        "<a href=\"${link cc_binary_args}\">args</a>",
+        "<a href=\"c-cpp.html#cc_binary_args\">args</a>");
+    checkExpandSingle(
+        "<a href=\"${link cc_binary_args}\">args</a>",
+        "<a href=\"#cc_binary_args\">args</a>");
   }
 
   @Test public void testRuleImplicitOutputsj() {
-    String docs = "<a href=\"${link cc_binary_implicit_outputs}\">args</a>";
-    String expected = "<a href=\"c-cpp.html#cc_binary_implicit_outputs\">args</a>";
-    assertEquals(expected, expander.expand(docs));
+    checkExpandMulti(
+        "<a href=\"${link cc_binary_implicit_outputs}\">args</a>",
+        "<a href=\"c-cpp.html#cc_binary_implicit_outputs\">args</a>");
+    checkExpandSingle(
+        "<a href=\"${link cc_binary_implicit_outputs}\">args</a>",
+        "<a href=\"#cc_binary_implicit_outputs\">args</a>");
   }
 
   @Test public void testStaticPageRef() {
-    String docs = "<a href=\"${link common-definitions}\">Common Definitions</a>";
-    String expected = "<a href=\"common-definitions.html\">Common Definitions</a>";
-    assertEquals(expected, expander.expand(docs));
+    checkExpandMulti(
+        "<a href=\"${link common-definitions}\">Common Definitions</a>",
+        "<a href=\"common-definitions.html\">Common Definitions</a>");
+    checkExpandSingle(
+        "<a href=\"${link common-definitions}\">Common Definitions</a>",
+        "<a href=\"#common-definitions\">Common Definitions</a>");
   }
 
   @Test(expected = IllegalArgumentException.class)
   public void testRefNotFound() {
     String docs = "<a href=\"${link foo.bar}\">bar</a>";
-    expander.expand(docs);
+    multiPageExpander.expand(docs);
   }
 
   @Test(expected = IllegalArgumentException.class)
   public void testIncorrectStaticPageHeadingLink() {
     String docs = "<a href=\"${link common-definitions.label-expansion}\">Label Expansion</a>";
-    expander.expand(docs);
+    multiPageExpander.expand(docs);
   }
 
   @Test public void testRuleHeadingLink() {
-    String docs = "<a href=\"${link cc_library#alwayslink_lib_example}\">examples</a>";
-    String expected = "<a href=\"c-cpp.html#alwayslink_lib_example\">examples</a>";
-    assertEquals(expected, expander.expand(docs));
+    checkExpandMulti(
+        "<a href=\"${link cc_library#alwayslink_lib_example}\">examples</a>",
+        "<a href=\"c-cpp.html#alwayslink_lib_example\">examples</a>");
+    checkExpandSingle(
+        "<a href=\"${link cc_library#alwayslink_lib_example}\">examples</a>",
+        "<a href=\"#alwayslink_lib_example\">examples</a>");
   }
 
   @Test public void testStaticPageHeadingLink() {
-    String docs =
-        "<a href=\"${link make-variables#predefined_variables.genrule.cmd}\">genrule cmd</a>";
-    String expected =
-        "<a href=\"make-variables.html#predefined_variables.genrule.cmd\">genrule cmd</a>";
-    assertEquals(expected, expander.expand(docs));
+    checkExpandMulti(
+        "<a href=\"${link make-variables#predefined_variables.genrule.cmd}\">genrule cmd</a>",
+        "<a href=\"make-variables.html#predefined_variables.genrule.cmd\">genrule cmd</a>");
+    checkExpandSingle(
+        "<a href=\"${link make-variables#predefined_variables.genrule.cmd}\">genrule cmd</a>",
+        "<a href=\"#predefined_variables.genrule.cmd\">genrule cmd</a>");
+  }
+
+  @Test public void testExpandRef() {
+    assertEquals(
+        "java.html#java_binary.runtime_deps",
+        multiPageExpander.expandRef("java_binary.runtime_deps"));
+    assertEquals(
+        "#java_binary.runtime_deps",
+        singlePageExpander.expandRef("java_binary.runtime_deps"));
   }
 }