Bazel DevSite: Add "create issue" & "view source" buttons to the gene…

…rated reference documentation.

- This change is a follow-up to unknown commit which added the buttons to all narrative docs.
- It only affects the documentation generated from Java sources. Consequently, the docs at https://bazel.build/rules/lib/repo are currently out-of-scope (since they are generated by StarDoc).

Implementation details:
- `_buttons.html` received some logic that controls whether the "view source" button should be displayed, and which URL it points to. This decision depends on the newly added `source_file` variable.
- All relevant `.vm` template files now include `_buttons.html` and set the `source_file` variable.

As a result, there are now three scenarios:
1. Narrative documentation remains unchanged since it does NOT set the `source_file` variable. As a result, the "view source" button is displayed, with an URL pointing to the current Markdown page.
2. Reference documentation that is generated from multiple source files has `source_file="NONE"`, which means that no "view source" button will be displayed.
3. Reference documentation that is generated from a single file stores the path of said file in the variable. In this case the button will be displayed, too.

A notable example of scenario 3 are Starlark modules, since they all use `starlark-library.vm`. Consequently, I modified `StarlarkDocumentationCollector` and `StarlarkBuiltinDoc` to inject the correct value into the `source_file` variable.

PiperOrigin-RevId: 486896353
Change-Id: I600fa17f07914a4f489c65de0b04cfce8f20b9ec

site/en/_buttons.html

@@ -1,6 +1,13 @@
 <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/issues/new?title=%5Bbazel.build%5D+Problem+with+{% dynamic print request.path %}&labels=type%3A%20documentation%20%28cleanup%29" target="_blank">
   Report an issue<span class="material-icons icon-after" aria-hidden="true">open_in_new</span>
 </a>
+{% dynamic if not setvar.source_file %}
 <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/tree/master/site/en{% dynamic print request.path %}.md" target="_blank">
   View source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span>
 </a>
+{% dynamic elif setvar.source_file != "NONE" %}
+<a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/tree/master/{% dynamic print setvar.source_file %}" target="_blank">
+  View source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span>
+</a>
+{% dynamic endif %}
+</p>

src/main/java/com/google/devtools/build/docgen/StarlarkDocumentationCollector.java

@@ -80,7 +80,11 @@ static ImmutableMap<String, StarlarkBuiltinDoc> collectModules(
     modules.put(
         topLevelModule.name(),
         new StarlarkBuiltinDoc(
-            topLevelModule, /*title=*/ "Globals", TopLevelModule.class, expander));
+            topLevelModule,
+            /*title=*/ "Globals",
+            TopLevelModule.class,
+            expander,
+            /*isTopLevel=*/ true));
 
     // Creating module documentation is done in three passes.
     // 1. Add all classes/interfaces annotated with @StarlarkBuiltin with documented = true.

src/main/java/com/google/devtools/build/docgen/starlark/StarlarkBuiltinDoc.java

@@ -40,9 +40,22 @@ public final class StarlarkBuiltinDoc extends StarlarkDoc {
   private final Multimap<String, StarlarkJavaMethodDoc> javaMethods;
   private TreeMap<String, StarlarkMethodDoc> methodMap;
   @Nullable private StarlarkConstructorMethodDoc javaConstructor;
+  private final boolean isTopLevel;
+
+  private static final String SOURCE_ROOT = "src/main/java";
+  private static final String NO_SOURCE_FILE_VALUE = "NONE";
 
   public StarlarkBuiltinDoc(
       StarlarkBuiltin module, String title, Class<?> classObject, StarlarkDocExpander expander) {
+    this(module, title, classObject, expander, false);
+  }
+
+  public StarlarkBuiltinDoc(
+      StarlarkBuiltin module,
+      String title,
+      Class<?> classObject,
+      StarlarkDocExpander expander,
+      boolean isTopLevel) {
     super(expander);
     this.module =
         Preconditions.checkNotNull(
@@ -51,6 +64,7 @@ public StarlarkBuiltinDoc(
     this.classObject = classObject;
     this.methodMap = new TreeMap<>(Collator.getInstance(Locale.US));
     this.javaMethods = HashMultimap.<String, StarlarkJavaMethodDoc>create();
+    this.isTopLevel = isTopLevel;
   }
 
   @Override
@@ -135,4 +149,13 @@ public ImmutableCollection<? extends StarlarkMethodDoc> getMethods() {
     }
     return methods.addAll(methodMap.values()).build();
   }
+
+  public String getSourceFile() {
+    if (isTopLevel) {
+      return NO_SOURCE_FILE_VALUE;
+    }
+
+    String[] parts = classObject.getName().split("\\$", -1);
+    return String.format("%s/%s.java", SOURCE_ROOT, parts[0].replace('.', '/'));
+  }
 }

src/main/java/com/google/devtools/build/docgen/templates/be/common-definitions.vm

@@ -12,6 +12,8 @@
 
 <h1 class="page-title" id="common-definitions">Common definitions</h1>
 
+{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/common-definitions.vm" %}
+{% include "_buttons.html" %}
 <p>This section defines various terms and concepts that are common to
 many functions or build rules.
 </p>

src/main/java/com/google/devtools/build/docgen/templates/be/functions.vm

@@ -12,6 +12,9 @@
 
 <h1 class="page-title">Functions</h1>
 
+{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/functions.vm" %}
+{% include "_buttons.html" %}
+
 #if (!$singlePage)
 <h2>Contents</h2>
 <ul>

src/main/java/com/google/devtools/build/docgen/templates/be/make-variables.vm

@@ -16,6 +16,9 @@
 -->
 <h1 class="page-title" id="make-variables">"Make" Variables</h1>
 
+{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/make-variables.vm" %}
+{% include "_buttons.html" %}
+
 #if (!$singlePage)
 <ul>
   <li><a href="#use">Use</a></li>

src/main/java/com/google/devtools/build/docgen/templates/be/overview.vm

@@ -6,6 +6,9 @@
 <body>
 
 <h1 class="page-title">Bazel BUILD Encyclopedia of Functions</h1>
+
+{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/overview.vm" %}
+{% include "_buttons.html" %}
 <h2>Concepts and terminology</h2>
 
 <ul>

src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm

@@ -14,6 +14,9 @@
 
 <h1 class="page-title">${ruleFamily.name} Rules</h1>
 
+{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %}
+{% include "_buttons.html" %}
+
 ${ruleFamily.summary}
 
 #if (!$singlePage)

src/main/java/com/google/devtools/build/docgen/templates/starlark-category.vm

@@ -6,6 +6,8 @@
 <body>
 <h1 class="page-title">${category.title}</h1>
 
+{% dynamic setvar source_file "NONE" %}
+{% include "_buttons.html" %}
 ${description}
 
 <ul>

src/main/java/com/google/devtools/build/docgen/templates/starlark-library.vm

@@ -7,6 +7,8 @@
 
 <h1 class="page-title" id="modules.${module.name}">${module.title}</h1>
 
+{% dynamic setvar source_file "${module.sourceFile}" %}
+{% include "_buttons.html" %}
 <!-- {% raw %} -->
 
 ${module.documentation}

src/main/java/com/google/devtools/build/docgen/templates/starlark-overview.vm

@@ -6,6 +6,8 @@
 <body>
 <h1 class="page-title">One-Page Overview</h1>
 
+{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/starlark-overview.vm" %}
+{% include "_buttons.html" %}
 A list of all modules and globals that are available:
 
 <h2>