Include load in summaries

.bazelci/presubmit.yml

@@ -35,15 +35,11 @@ matrix:
     - "//test/..."
   test_flags: *noenable_bzlmod_flags
   test_targets:
-  # Some tests are expected to fail in legacy WORKSPACE mode due to repo name change
-    - "//test/..."
-    - "-//test:attribute_defaults_test"
-    - "-//test:function_wrap_multiple_lines_test"
-    - "-//test:misc_apis_test"
-    - "-//test:module_extension_test"
-    - "-//test:proto_format_test"
-    - "-//test:stardoc_self_gen_test"
-    - "-//test:table_of_contents_test"
+  # Most tests will not pass in legacy WORKSPACE mode due to repo name change
+    - "//test:multiple_files_noenable_bzlmod_test"
+    - "//test:same_level_file_noenable_bzlmod_test"
+    - "//test:table_of_contents_noenable_bzlmod_test"
+    - "//test:local_repository_test"
 
 .windows_task_config: &windows_task_config
   <<: *common_task_config
@@ -61,7 +57,7 @@ tasks:
     name: Build and test - Windows
     platform: windows
 
-  legacy_workspace:
+  noenable_bzlmod:
     <<: *noenable_bzlmod_task_config
     name: Build and test - legacy WORKSPACE setup
     platform: ${{ platform }}

docs/stardoc_rule.md

@@ -7,6 +7,8 @@ Starlark rule for stardoc: a documentation generator tool written in Java.
 ## stardoc
 
 <pre>
+load("@stardoc//stardoc:stardoc.bzl", "stardoc")
+
 stardoc(*, <a href="#stardoc-name">name</a>, <a href="#stardoc-input">input</a>, <a href="#stardoc-out">out</a>, <a href="#stardoc-deps">deps</a>, <a href="#stardoc-format">format</a>, <a href="#stardoc-symbol_names">symbol_names</a>, <a href="#stardoc-renderer">renderer</a>, <a href="#stardoc-aspect_template">aspect_template</a>, <a href="#stardoc-func_template">func_template</a>,
         <a href="#stardoc-header_template">header_template</a>, <a href="#stardoc-table_of_contents_template">table_of_contents_template</a>, <a href="#stardoc-provider_template">provider_template</a>, <a href="#stardoc-rule_template">rule_template</a>,
         <a href="#stardoc-repository_rule_template">repository_rule_template</a>, <a href="#stardoc-module_extension_template">module_extension_template</a>, <a href="#stardoc-footer_template">footer_template</a>, <a href="#stardoc-render_main_repo_name">render_main_repo_name</a>,

src/main/java/com/google/devtools/build/stardoc/renderer/RendererMain.java

@@ -38,6 +38,7 @@
 import java.io.PrintWriter;
 import java.util.Comparator;
 import java.util.List;
+import java.util.Optional;
 
 /**
  * Main entry point for Renderer binary.
@@ -92,7 +93,9 @@ public void println() {
               rendererOptions.aspectTemplateFilePath,
               rendererOptions.repositoryRuleTemplateFilePath,
               rendererOptions.moduleExtensionTemplateFilePath,
-              !moduleInfo.getFile().isEmpty() ? moduleInfo.getFile() : "...",
+              !moduleInfo.getFile().isEmpty()
+                  ? Optional.of(moduleInfo.getFile())
+                  : Optional.empty(),
               rendererOptions.footerTemplateFilePath,
               stamping);
 

src/main/java/com/google/devtools/build/stardoc/rendering/MarkdownRenderer.java

@@ -41,6 +41,7 @@
 import java.nio.file.Path;
 import java.nio.file.Paths;
 import java.util.List;
+import java.util.Optional;
 
 /** Produces stardoc output in markdown form. */
 public class MarkdownRenderer {
@@ -58,7 +59,7 @@ public interface Renderer<T> {
   private final String aspectTemplateFilename;
   private final String repositoryRuleTemplateFilename;
   private final String moduleExtensionTemplateFilename;
-  private final String extensionBzlFile;
+  private final Optional<String> entrypointBzlFile;
   private final String footerTemplateFilename;
   private final Stamping stamping;
 
@@ -71,7 +72,7 @@ public MarkdownRenderer(
       String aspectTemplate,
       String repositoryRuleTemplate,
       String moduleExtensionTemplate,
-      String extensionBzlFile,
+      Optional<String> entrypointBzlFile,
       String footerTemplate,
       Stamping stamping) {
     this.headerTemplateFilename = headerTemplate;
@@ -82,7 +83,7 @@ public MarkdownRenderer(
     this.aspectTemplateFilename = aspectTemplate;
     this.repositoryRuleTemplateFilename = repositoryRuleTemplate;
     this.moduleExtensionTemplateFilename = moduleExtensionTemplate;
-    this.extensionBzlFile = extensionBzlFile;
+    this.entrypointBzlFile = entrypointBzlFile;
     this.footerTemplateFilename = footerTemplate;
     this.stamping = stamping;
   }
@@ -95,7 +96,7 @@ public String renderMarkdownHeader(ModuleInfo moduleInfo) throws IOException {
     ImmutableMap<String, Object> vars =
         ImmutableMap.of(
             "util",
-            new MarkdownUtil(extensionBzlFile),
+            new MarkdownUtil(entrypointBzlFile),
             "moduleDocstring",
             moduleInfo.getModuleDocstring(),
             "stamping",
@@ -123,7 +124,7 @@ public String renderTableOfContents(
 
     ImmutableMap<String, Object> vars =
         ImmutableMap.of(
-            "util", new MarkdownUtil(extensionBzlFile),
+            "util", new MarkdownUtil(entrypointBzlFile),
             "ruleInfos", ruleInfos,
             "providerInfos", providerInfos,
             "functionInfos", starlarkFunctions,
@@ -146,7 +147,7 @@ public String render(RuleInfo ruleInfo) throws IOException {
     ImmutableMap<String, Object> vars =
         ImmutableMap.of(
             "util",
-            new MarkdownUtil(extensionBzlFile),
+            new MarkdownUtil(entrypointBzlFile),
             "ruleName",
             ruleInfo.getRuleName(),
             "ruleInfo",
@@ -224,7 +225,7 @@ public String render(ProviderInfo providerInfo) throws IOException {
     ImmutableMap<String, Object> vars =
         ImmutableMap.of(
             "util",
-            new MarkdownUtil(extensionBzlFile),
+            new MarkdownUtil(entrypointBzlFile),
             "providerName",
             providerInfo.getProviderName(),
             "providerInfo",
@@ -263,7 +264,7 @@ private static FunctionParamInfo withInferredDoc(
    */
   public String render(StarlarkFunctionInfo functionInfo) throws IOException {
     ImmutableMap<String, Object> vars =
-        ImmutableMap.of("util", new MarkdownUtil(extensionBzlFile), "funcInfo", functionInfo);
+        ImmutableMap.of("util", new MarkdownUtil(entrypointBzlFile), "funcInfo", functionInfo);
     Reader reader = readerFromPath(functionTemplateFilename);
     try {
       return Template.parseFrom(reader).evaluate(vars);
@@ -280,7 +281,7 @@ public String render(AspectInfo aspectInfo) throws IOException {
     ImmutableMap<String, Object> vars =
         ImmutableMap.of(
             "util",
-            new MarkdownUtil(extensionBzlFile),
+            new MarkdownUtil(entrypointBzlFile),
             "aspectName",
             aspectInfo.getAspectName(),
             "aspectInfo",
@@ -301,7 +302,7 @@ public String render(RepositoryRuleInfo repositoryRuleInfo) throws IOException {
     ImmutableMap<String, Object> vars =
         ImmutableMap.of(
             "util",
-            new MarkdownUtil(extensionBzlFile),
+            new MarkdownUtil(entrypointBzlFile),
             "ruleName",
             repositoryRuleInfo.getRuleName(),
             "ruleInfo",
@@ -322,7 +323,7 @@ public String render(ModuleExtensionInfo moduleExtensionInfo) throws IOException
     ImmutableMap<String, Object> vars =
         ImmutableMap.of(
             "util",
-            new MarkdownUtil(extensionBzlFile),
+            new MarkdownUtil(entrypointBzlFile),
             "extensionName",
             moduleExtensionInfo.getExtensionName(),
             "extensionInfo",
@@ -338,7 +339,7 @@ public String render(ModuleExtensionInfo moduleExtensionInfo) throws IOException
   /** Returns a markdown header string that should appear at the end of Stardoc's output. */
   public String renderMarkdownFooter(ModuleInfo moduleInfo) throws IOException {
     ImmutableMap<String, Object> vars =
-        ImmutableMap.of("util", new MarkdownUtil(extensionBzlFile), "stamping", stamping);
+        ImmutableMap.of("util", new MarkdownUtil(entrypointBzlFile), "stamping", stamping);
     Reader reader = readerFromPath(footerTemplateFilename);
     try {
       return Template.parseFrom(reader).evaluate(vars);

src/main/java/com/google/devtools/build/stardoc/rendering/MarkdownUtil.java

@@ -47,12 +47,12 @@
 
 /** Contains a number of utility methods for markdown rendering. */
 public final class MarkdownUtil {
-  private final String extensionBzlFile;
+  private final Optional<String> entrypointBzlFile;
 
   private static final int MAX_LINE_LENGTH = 100;
 
-  public MarkdownUtil(String extensionBzlFile) {
-    this.extensionBzlFile = extensionBzlFile;
+  public MarkdownUtil(Optional<String> entrypointBzlFile) {
+    this.entrypointBzlFile = entrypointBzlFile;
   }
 
   /**
@@ -307,7 +307,8 @@ public String moduleExtensionSummary(String extensionName, ModuleExtensionInfo e
     StringBuilder summaryBuilder = new StringBuilder();
     summaryBuilder.append(
         String.format(
-            "%s = use_extension(\"%s\", \"%s\")", extensionName, extensionBzlFile, extensionName));
+            "%s = use_extension(\"%s\", \"%s\")",
+            extensionName, entrypointBzlFile.orElse("..."), extensionName));
     for (ModuleExtensionTagClassInfo tagClass : extensionInfo.getTagClassList()) {
       String callableName = String.format("%s.%s", extensionName, tagClass.getTagName());
       ImmutableList<Param> params =
@@ -331,6 +332,13 @@ public String funcSummary(StarlarkFunctionInfo funcInfo) {
         getFunctionParamsInDeclarationOrder(funcInfo, funcInfo.getFunctionName()));
   }
 
+  @SuppressWarnings("unused") // Used by markdown template.
+  public String loadStatement(String name) {
+    return entrypointBzlFile
+        .map(file -> String.format("load(\"%s\", \"%s\")", file, name.split("\\.")[0]))
+        .orElse("");
+  }
+
   /**
    * Returns a string representing the summary for a function or other callable.
    *

src/test/java/com/google/devtools/build/stardoc/rendering/MarkdownUtilTest.java

@@ -16,6 +16,7 @@
 
 import static com.google.common.truth.Truth.assertThat;
 
+import java.util.Optional;
 import org.junit.Test;
 import org.junit.runner.RunWith;
 import org.junit.runners.JUnit4;
@@ -24,7 +25,7 @@
 @RunWith(JUnit4.class)
 public class MarkdownUtilTest {
 
-  MarkdownUtil util = new MarkdownUtil("//:test.bzl");
+  MarkdownUtil util = new MarkdownUtil(Optional.of("//:test.bzl"));
 
   @Test
   public void markdownCodeSpan() {

stardoc/templates/html_tables/aspect.vm

@@ -3,6 +3,8 @@
 #[[##]]# ${aspectName}
 
 <pre>
+${util.loadStatement($aspectName)}
+
 ${util.aspectSummary($aspectName, $aspectInfo)}
 </pre>
 

stardoc/templates/html_tables/func.vm

@@ -3,6 +3,8 @@
 #[[##]]# ${funcInfo.functionName}
 
 <pre>
+${util.loadStatement($funcInfo.functionName)}
+
 ${util.funcSummary($funcInfo)}
 </pre>
 

stardoc/templates/html_tables/provider.vm

@@ -8,6 +8,8 @@
 #[[##]]# ${providerName}
 
 <pre>
+${util.loadStatement($providerName)}
+
 #if ($providerInfo.hasInit() && !$mergeParamsAndFields)
 ${util.providerSummaryWithInitAnchor($providerName, $providerInfo)}
 #else

stardoc/templates/html_tables/repository_rule.vm

@@ -3,6 +3,8 @@
 #[[##]]# ${ruleName}
 
 <pre>
+${util.loadStatement($ruleName)}
+
 ${util.repositoryRuleSummary($ruleName, $ruleInfo)}
 </pre>
 #if (!$ruleInfo.docString.isEmpty())

stardoc/templates/html_tables/rule.vm

@@ -3,6 +3,8 @@
 #[[##]]# ${ruleName}
 
 <pre>
+${util.loadStatement($ruleName)}
+
 ${util.ruleSummary($ruleName, $ruleInfo)}
 </pre>
 

stardoc/templates/markdown_tables/aspect.vm

@@ -3,6 +3,8 @@
 #[[##]]# ${aspectName}
 
 <pre>
+${util.loadStatement($aspectName)}
+
 ${util.aspectSummary($aspectName, $aspectInfo)}
 </pre>
 

stardoc/templates/markdown_tables/func.vm

@@ -3,6 +3,8 @@
 #[[##]]# ${funcInfo.functionName}
 
 <pre>
+${util.loadStatement($funcInfo.functionName)}
+
 ${util.funcSummary($funcInfo)}
 </pre>
 

stardoc/templates/markdown_tables/provider.vm

@@ -8,6 +8,8 @@
 #[[##]]# ${providerName}
 
 <pre>
+${util.loadStatement($providerName)}
+
 #if ($providerInfo.hasInit() && !$mergeParamsAndFields)
 ${util.providerSummaryWithInitAnchor($providerName, $providerInfo)}
 #else

stardoc/templates/markdown_tables/repository_rule.vm

@@ -3,6 +3,8 @@
 #[[##]]# ${ruleName}
 
 <pre>
+${util.loadStatement($ruleName)}
+
 ${util.repositoryRuleSummary($ruleName, $ruleInfo)}
 </pre>
 #if (!$ruleInfo.docString.isEmpty())

stardoc/templates/markdown_tables/rule.vm

@@ -3,6 +3,8 @@
 #[[##]]# ${ruleName}
 
 <pre>
+${util.loadStatement($ruleName)}
+
 ${util.ruleSummary($ruleName, $ruleInfo)}
 </pre>
 

test/BUILD

@@ -119,6 +119,20 @@ stardoc_test(
     ],
 )
 
+stardoc_test(
+    name = "multiple_files_noenable_bzlmod_test",
+    golden_file = "testdata/multiple_files_test/noenable_bzlmod_golden.md",
+    input_file = "testdata/multiple_files_test/input.bzl",
+    tags = [
+        "manual",
+        "noenable_bzlmod",
+    ],
+    deps = [
+        "testdata/multiple_files_test/dep.bzl",
+        "testdata/multiple_files_test/inner_dep.bzl",
+    ],
+)
+
 stardoc_test(
     name = "same_level_file_test",
     golden_file = "//test/testdata/same_level_file_test:golden.md",
@@ -129,6 +143,20 @@ stardoc_test(
     ],
 )
 
+stardoc_test(
+    name = "same_level_file_noenable_bzlmod_test",
+    golden_file = "//test/testdata/same_level_file_test:noenable_bzlmod_golden.md",
+    input_file = "//test/testdata/same_level_file_test:input.bzl",
+    symbol_names = ["my_rule"],
+    tags = [
+        "manual",
+        "noenable_bzlmod",
+    ],
+    deps = [
+        "//test/testdata/same_level_file_test:dep.bzl",
+    ],
+)
+
 stardoc_test(
     name = "misc_apis_test",
     golden_file = "testdata/misc_apis_test/golden.md",
@@ -306,6 +334,18 @@ stardoc_test(
     deps = [":table_of_contents_test_deps"],
 )
 
+stardoc_test(
+    name = "table_of_contents_noenable_bzlmod_test",
+    golden_file = "testdata/table_of_contents_test/noenable_bzlmod_golden.md",
+    input_file = "testdata/table_of_contents_test/input.bzl",
+    table_of_contents_template = "//stardoc:templates/markdown_tables/table_of_contents.vm",
+    tags = [
+        "manual",
+        "noenable_bzlmod",
+    ],
+    deps = [":table_of_contents_test_deps"],
+)
+
 stardoc_test(
     name = "stamping_test",
     golden_file = "testdata/stamping_test/golden.md",
@@ -323,7 +363,7 @@ stardoc_test(
 )
 
 sh_test(
-    name = "local_repository_test_e2e_test",
+    name = "local_repository_test",
     srcs = ["diff_test_runner.sh"],
     args = [
         "$(location @local_repository_test//:output.md)",

test/bzlmod/MODULE.bazel

@@ -1,3 +1,5 @@
+module(name = "test_module")
+
 bazel_dep(name = "stardoc", version = "")
 local_path_override(
     module_name = "stardoc",