Bazel DocGen: Fix RuleLinkExpander to produce correct links in single-page build encyclopedia.
https://github.com/bazelbuild/bazel/commit/bcf5b1753f745a323290a87dbb83734c40935c31 changed the RuleLinkExpander so that all links in the single-page BE pointed to itself. This was incorrect, since only some of the pages (namely common-definitions and make-variables) were replaced by the single-page BE. Others remained separate pages, irregardless of whether a single-page or a multi-page BE was built.
PiperOrigin-RevId: 439646208
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 bce5046..242820b 100644
--- a/src/main/java/com/google/devtools/build/docgen/RuleLinkExpander.java
+++ b/src/main/java/com/google/devtools/build/docgen/RuleLinkExpander.java
@@ -14,6 +14,7 @@
package com.google.devtools.build.docgen;
import com.google.common.collect.ImmutableMap;
+import com.google.common.collect.ImmutableSet;
import java.nio.file.Paths;
import java.util.HashMap;
import java.util.Map;
@@ -46,6 +47,11 @@
.put("select", FUNCTIONS_PAGE)
.buildOrThrow();
+ // These static pages only exist in the multi-page BE. In the single-page BE
+ // their content is part of the BE.
+ private static final ImmutableSet<String> STATIC_PAGES_REPLACED_BY_SINGLE_PAGE_BE =
+ ImmutableSet.<String>of("common-definitions", "make-variables");
+
private final DocLinkMap linkMap;
private final Map<String, String> ruleIndex = new HashMap<>();
private final boolean singlePage;
@@ -125,7 +131,10 @@
// common-definitions. Generate a link to that page.
String mapping = linkMap.values.get(name);
if (mapping != null) {
- String link = singlePage ? "#" + name : mapping;
+ String link =
+ singlePage && STATIC_PAGES_REPLACED_BY_SINGLE_PAGE_BE.contains(name)
+ ? "#" + name
+ : mapping;
// For referencing headings on a static page, use the following syntax:
// ${link static_page_name#heading_name}, example: ${link make-variables#gendir}
String pageHeading = matcher.group(4);
@@ -191,9 +200,11 @@
if (headingMapping != null || pageMapping != null) {
String link;
- if (singlePage) {
- // Special case: For the single-page BE we don't use the value of the mapping, we just
- // need to know that there is one (since that means `name` is a legitimate BE page).
+ if (singlePage && STATIC_PAGES_REPLACED_BY_SINGLE_PAGE_BE.contains(name)) {
+ // Special case: Some of the stand-alone files in the multi-page BE are made redundant
+ // by the BE in the single-page case. Consequently, we ignore the value of the mapping
+ // in this case (we only need to know that the mapping exists, since this means it is
+ // a legitimate reference).
link = "#" + heading;
} else if (headingMapping != null) {
// Multi-page BE where page#heading has to be redirected.
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 09922bc..257ab99 100644
--- a/src/test/java/com/google/devtools/build/docgen/RuleLinkExpanderTest.java
+++ b/src/test/java/com/google/devtools/build/docgen/RuleLinkExpanderTest.java
@@ -45,7 +45,9 @@
"make-variables",
"make-variables.html",
"common-definitions",
- "common-definitions.html"));
+ "common-definitions.html",
+ "standalone",
+ "standalone.html"));
multiPageExpander = new RuleLinkExpander(index, false, linkMap);
singlePageExpander = new RuleLinkExpander(index, true, linkMap);
}
@@ -112,7 +114,8 @@
"<a href=\"#cc_binary_implicit_outputs\">args</a>");
}
- @Test public void testStaticPageRef() {
+ @Test
+ public void testStaticPageRef_pageReplacedBySinglePageBE() {
checkExpandMulti(
"<a href=\"${link common-definitions}\">Common Definitions</a>",
"<a href=\"common-definitions.html\">Common Definitions</a>");
@@ -122,6 +125,16 @@
}
@Test
+ public void testStaticPageRef_separatePage() {
+ checkExpandMulti(
+ "<a href=\"${link standalone}\">standalone</a>",
+ "<a href=\"standalone.html\">standalone</a>");
+ checkExpandSingle(
+ "<a href=\"${link standalone}\">standalone</a>",
+ "<a href=\"standalone.html\">standalone</a>");
+ }
+
+ @Test
public void testRefNotFound() {
String docs = "<a href=\"${link foo.bar}\">bar</a>";
assertThrows(
@@ -150,7 +163,8 @@
"<a href=\"#alwayslink_lib_example\">examples</a>");
}
- @Test public void testStaticPageHeadingLink() {
+ @Test
+ public void testStaticPageHeadingLink_pageReplacedBySinglePageBE() {
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>");
@@ -159,6 +173,16 @@
"<a href=\"#predefined_variables.genrule.cmd\">genrule cmd</a>");
}
+ @Test
+ public void testStaticPageHeadingLink_separatePage() {
+ checkExpandMulti(
+ "<a href=\"${link standalone#foobar}\">standalone</a>",
+ "<a href=\"standalone.html#foobar\">standalone</a>");
+ checkExpandSingle(
+ "<a href=\"${link standalone#foobar}\">standalone</a>",
+ "<a href=\"standalone.html#foobar\">standalone</a>");
+ }
+
@Test public void testExpandRef() {
assertThat(multiPageExpander.expandRef("java_binary.runtime_deps"))
.isEqualTo("java.html#java_binary.runtime_deps");
