Bazel DocGen (1/3): Make link expansion mechanism more powerful.
# Motivation
Linking from one part of the Blaze/Bazel (“Blazel”) documentation to another one is surprisingly difficult due to various distinctions (native code vs Starlark, Blaze vs Bazel, generated vs narrative documentation). As a result, we’ve implemented various hacks or simply tolerated broken links.
# Contributions
This CL addresses the problems by doubling down on dynamic link expansion:
- RuleLinkExpander can now be used to link to any file in the build encyclopedia (“BE”): While the `${link foo}` syntax was originally intended for linking to rule families, a previous version already contained a hack to link to some static documentation files. This CL super-charges RuleLinkExpander by allowing it to link to *any* BE file, based on an explicit link mapping that has to be defined in a JSON configuration file. As a result, it’s clearly visible which files diverge between Blaze and Bazel.
- Introduction of StarlarkDocExpander: This new class is a proxy for the improved RuleLinkExpander as well as StarlarkDocUtils.substituteVariables(). As a result, Starlark documentation can now easily link to pages in the BE.
# Why JSON?
JSON is a lightweight configuration format, and luckily both Bazel and Blaze already have a JSON parser (GSON) among their dependencies.
# Downsides
The Starlark DocGen code is a love letter to the `static` modifier, which unfortunately means that we have to pass the StarlarkDocExpander instance through many methods.
# Alternatives
We could have passed the StarlarkDocExpander instance to the Velocity Template engine, which would have allowed us to call the expand() method from within the templates. However, I think it’s easier to figure out what happens if the real logic happens inside Java.
PiperOrigin-RevId: 433039776
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 d6d32a2..9d967dd 100644
--- a/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java
+++ b/src/main/java/com/google/devtools/build/docgen/DocgenConsts.java
@@ -176,12 +176,10 @@
// The following variables are not constants as they can be overridden from
// StarlarkDocumentationProcessor#parseOptions
+ // Their purpose is to allow generated Starlark documentation to link into the build encyclopedia.
- // Build Encyclopedia documentation root
- public static String BeDocsRoot = "/versions/main/be";
-
- // Documentation files extension
- public static String documentationExtension = "html";
+ // Root directory of *narrative* Starlark documentation files such as rules.md
+ public static String starlarkDocsRoot = "/rules";
static String toCommandLineFormat(String cmdDoc) {
// Replace html <br> tags with line breaks
