diff --git a/.bazelci/presubmit.yml b/.bazelci/presubmit.yml index a6ba4ccc..79291a0f 100644 --- a/.bazelci/presubmit.yml +++ b/.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 }} diff --git a/docs/stardoc_rule.md b/docs/stardoc_rule.md index 9851880e..83569e4f 100644 --- a/docs/stardoc_rule.md +++ b/docs/stardoc_rule.md @@ -7,6 +7,8 @@ Starlark rule for stardoc: a documentation generator tool written in Java. ## stardoc
+load("@stardoc//stardoc:stardoc.bzl", "stardoc") + stardoc(*, name, input, out, deps, format, symbol_names, renderer, aspect_template, func_template, header_template, table_of_contents_template, provider_template, rule_template, repository_rule_template, module_extension_template, footer_template, render_main_repo_name, diff --git a/src/main/java/com/google/devtools/build/stardoc/renderer/RendererMain.java b/src/main/java/com/google/devtools/build/stardoc/renderer/RendererMain.java index fc8fca05..21bd2fa8 100644 --- a/src/main/java/com/google/devtools/build/stardoc/renderer/RendererMain.java +++ b/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); diff --git a/src/main/java/com/google/devtools/build/stardoc/rendering/MarkdownRenderer.java b/src/main/java/com/google/devtools/build/stardoc/rendering/MarkdownRenderer.java index c2eb8762..db1fdc59 100644 --- a/src/main/java/com/google/devtools/build/stardoc/rendering/MarkdownRenderer.java +++ b/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@@ -110,6 +120,8 @@ macro_with_args_kwonlys_and_kwargs(name, number, args, kwargs) @@ -138,6 +150,8 @@ An empty list. ## macro_with_kwargs{ private final String aspectTemplateFilename; private final String repositoryRuleTemplateFilename; private final String moduleExtensionTemplateFilename; - private final String extensionBzlFile; + private final Optional entrypointBzlFile; private final String footerTemplateFilename; private final Stamping stamping; @@ -71,7 +72,7 @@ public MarkdownRenderer( String aspectTemplate, String repositoryRuleTemplate, String moduleExtensionTemplate, - String extensionBzlFile, + Optional 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 vars = ImmutableMap.of( "util", - new MarkdownUtil(extensionBzlFile), + new MarkdownUtil(entrypointBzlFile), "moduleDocstring", moduleInfo.getModuleDocstring(), "stamping", @@ -123,7 +124,7 @@ public String renderTableOfContents( ImmutableMap 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 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 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 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 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 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 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 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); diff --git a/src/main/java/com/google/devtools/build/stardoc/rendering/MarkdownUtil.java b/src/main/java/com/google/devtools/build/stardoc/rendering/MarkdownUtil.java index 9324bb65..8b383d9b 100644 --- a/src/main/java/com/google/devtools/build/stardoc/rendering/MarkdownUtil.java +++ b/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 entrypointBzlFile; private static final int MAX_LINE_LENGTH = 100; - public MarkdownUtil(String extensionBzlFile) { - this.extensionBzlFile = extensionBzlFile; + public MarkdownUtil(Optional 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 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. * diff --git a/src/test/java/com/google/devtools/build/stardoc/rendering/MarkdownUtilTest.java b/src/test/java/com/google/devtools/build/stardoc/rendering/MarkdownUtilTest.java index 82fdfadd..4f70ba71 100644 --- a/src/test/java/com/google/devtools/build/stardoc/rendering/MarkdownUtilTest.java +++ b/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() { diff --git a/stardoc/templates/html_tables/aspect.vm b/stardoc/templates/html_tables/aspect.vm index e66b2b29..7033279c 100644 --- a/stardoc/templates/html_tables/aspect.vm +++ b/stardoc/templates/html_tables/aspect.vm @@ -3,6 +3,8 @@ #[[##]]# ${aspectName} +${util.loadStatement($aspectName)} + ${util.aspectSummary($aspectName, $aspectInfo)}diff --git a/stardoc/templates/html_tables/func.vm b/stardoc/templates/html_tables/func.vm index b52e5bca..7d9191dd 100644 --- a/stardoc/templates/html_tables/func.vm +++ b/stardoc/templates/html_tables/func.vm @@ -3,6 +3,8 @@ #[[##]]# ${funcInfo.functionName}+${util.loadStatement($funcInfo.functionName)} + ${util.funcSummary($funcInfo)}diff --git a/stardoc/templates/html_tables/provider.vm b/stardoc/templates/html_tables/provider.vm index a2919b09..4684676b 100644 --- a/stardoc/templates/html_tables/provider.vm +++ b/stardoc/templates/html_tables/provider.vm @@ -8,6 +8,8 @@ #[[##]]# ${providerName}+${util.loadStatement($providerName)} + #if ($providerInfo.hasInit() && !$mergeParamsAndFields) ${util.providerSummaryWithInitAnchor($providerName, $providerInfo)} #else diff --git a/stardoc/templates/html_tables/repository_rule.vm b/stardoc/templates/html_tables/repository_rule.vm index 23785625..90df09b3 100644 --- a/stardoc/templates/html_tables/repository_rule.vm +++ b/stardoc/templates/html_tables/repository_rule.vm @@ -3,6 +3,8 @@ #[[##]]# ${ruleName}@@ -138,6 +150,8 @@ An empty list. ## macro_with_kwargs+${util.loadStatement($ruleName)} + ${util.repositoryRuleSummary($ruleName, $ruleInfo)}#if (!$ruleInfo.docString.isEmpty()) diff --git a/stardoc/templates/html_tables/rule.vm b/stardoc/templates/html_tables/rule.vm index 0d5b6382..546e0c1b 100644 --- a/stardoc/templates/html_tables/rule.vm +++ b/stardoc/templates/html_tables/rule.vm @@ -3,6 +3,8 @@ #[[##]]# ${ruleName}+${util.loadStatement($ruleName)} + ${util.ruleSummary($ruleName, $ruleInfo)}diff --git a/stardoc/templates/markdown_tables/aspect.vm b/stardoc/templates/markdown_tables/aspect.vm index 36aa47a0..327bf108 100644 --- a/stardoc/templates/markdown_tables/aspect.vm +++ b/stardoc/templates/markdown_tables/aspect.vm @@ -3,6 +3,8 @@ #[[##]]# ${aspectName}+${util.loadStatement($aspectName)} + ${util.aspectSummary($aspectName, $aspectInfo)}diff --git a/stardoc/templates/markdown_tables/func.vm b/stardoc/templates/markdown_tables/func.vm index e53b81a9..5d529fc6 100644 --- a/stardoc/templates/markdown_tables/func.vm +++ b/stardoc/templates/markdown_tables/func.vm @@ -3,6 +3,8 @@ #[[##]]# ${funcInfo.functionName}+${util.loadStatement($funcInfo.functionName)} + ${util.funcSummary($funcInfo)}diff --git a/stardoc/templates/markdown_tables/provider.vm b/stardoc/templates/markdown_tables/provider.vm index f623e0d0..a198ac5e 100644 --- a/stardoc/templates/markdown_tables/provider.vm +++ b/stardoc/templates/markdown_tables/provider.vm @@ -8,6 +8,8 @@ #[[##]]# ${providerName}+${util.loadStatement($providerName)} + #if ($providerInfo.hasInit() && !$mergeParamsAndFields) ${util.providerSummaryWithInitAnchor($providerName, $providerInfo)} #else diff --git a/stardoc/templates/markdown_tables/repository_rule.vm b/stardoc/templates/markdown_tables/repository_rule.vm index 4473f012..579e76a4 100644 --- a/stardoc/templates/markdown_tables/repository_rule.vm +++ b/stardoc/templates/markdown_tables/repository_rule.vm @@ -3,6 +3,8 @@ #[[##]]# ${ruleName}@@ -110,6 +120,8 @@ macro_with_args_kwonlys_and_kwargs(name, number, *args, **kwargs)+${util.loadStatement($ruleName)} + ${util.repositoryRuleSummary($ruleName, $ruleInfo)}#if (!$ruleInfo.docString.isEmpty()) diff --git a/stardoc/templates/markdown_tables/rule.vm b/stardoc/templates/markdown_tables/rule.vm index 0b73239c..3b94cd59 100644 --- a/stardoc/templates/markdown_tables/rule.vm +++ b/stardoc/templates/markdown_tables/rule.vm @@ -3,6 +3,8 @@ #[[##]]# ${ruleName}+${util.loadStatement($ruleName)} + ${util.ruleSummary($ruleName, $ruleInfo)}diff --git a/test/BUILD b/test/BUILD index 971b9d9f..89f82654 100644 --- a/test/BUILD +++ b/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)", diff --git a/test/bzlmod/MODULE.bazel b/test/bzlmod/MODULE.bazel index 80bc2f9d..22b4b829 100644 --- a/test/bzlmod/MODULE.bazel +++ b/test/bzlmod/MODULE.bazel @@ -1,3 +1,5 @@ +module(name = "test_module") + bazel_dep(name = "stardoc", version = "") local_path_override( module_name = "stardoc", diff --git a/test/bzlmod/docs.md.golden b/test/bzlmod/docs.md.golden index 3b671cc0..33555173 100644 --- a/test/bzlmod/docs.md.golden +++ b/test/bzlmod/docs.md.golden @@ -7,6 +7,8 @@ A simple macro used to test stardoc. ## write_host_constraints+load("@test_module//:def.bzl", "write_host_constraints") + write_host_constraints(name)diff --git a/test/testdata/angle_bracket_test/golden.md b/test/testdata/angle_bracket_test/golden.md index 3e26beaf..9bbb7424 100644 --- a/test/testdata/angle_bracket_test/golden.md +++ b/test/testdata/angle_bracket_test/golden.md @@ -17,6 +17,8 @@ Angle brackets are also preserved in inline code blocks (`#include`). ## my_anglebrac +load("@stardoc//test:testdata/angle_bracket_test/input.bzl", "my_anglebrac") + my_anglebrac(name, also_useless, useless)@@ -37,6 +39,8 @@ Rule with \## bracketuse +load("@stardoc//test:testdata/angle_bracket_test/input.bzl", "bracketuse") + bracketuse(foo, bar, baz)@@ -56,6 +60,8 @@ Information with \## bracket_function +load("@stardoc//test:testdata/angle_bracket_test/input.bzl", "bracket_function") + bracket_function(param, md_string)@@ -93,6 +99,8 @@ deprecated for \as well as ` `. ## bracket_aspect +load("@stardoc//test:testdata/angle_bracket_test/input.bzl", "bracket_aspect") + bracket_aspect(name, brackets)diff --git a/test/testdata/apple_basic_test/golden.md b/test/testdata/apple_basic_test/golden.md index b9e7a5bf..8dbe2116 100644 --- a/test/testdata/apple_basic_test/golden.md +++ b/test/testdata/apple_basic_test/golden.md @@ -7,6 +7,8 @@ ## apple_related_rule+load("@stardoc//test:testdata/apple_basic_test/input.bzl", "apple_related_rule") + apple_related_rule(name, first, fourth, second, third)diff --git a/test/testdata/aspect_test/golden.md b/test/testdata/aspect_test/golden.md index e1ef986c..326e8720 100644 --- a/test/testdata/aspect_test/golden.md +++ b/test/testdata/aspect_test/golden.md @@ -7,6 +7,8 @@ The input file for the aspect test ## my_aspect_impl+load("@stardoc//test:testdata/aspect_test/input.bzl", "my_aspect_impl") + my_aspect_impl(ctx)@@ -25,6 +27,8 @@ my_aspect_impl(ctx) ## my_aspect+load("@stardoc//test:testdata/aspect_test/input.bzl", "my_aspect") + my_aspect(name, first, second)@@ -51,11 +55,38 @@ It does stuff. | second | - | String | required | | + + +## namespace.namespaced_aspect + ++load("@stardoc//test:testdata/aspect_test/input.bzl", "namespace") + +namespace.namespaced_aspect(name, third) ++ +This is another aspect. + +**ASPECT ATTRIBUTES** + + + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this target. | Name | required | | +| third | - | Integer | required | | + + ## other_aspect+load("@stardoc//test:testdata/aspect_test/input.bzl", "other_aspect") + other_aspect(name, third)diff --git a/test/testdata/aspect_test/input.bzl b/test/testdata/aspect_test/input.bzl index 38ddde0b..179ce038 100644 --- a/test/testdata/aspect_test/input.bzl +++ b/test/testdata/aspect_test/input.bzl @@ -28,3 +28,7 @@ other_aspect = aspect( "third": attr.int(mandatory = True), }, ) + +namespace = struct( + namespaced_aspect = other_aspect, +) diff --git a/test/testdata/attribute_defaults_test/golden.md b/test/testdata/attribute_defaults_test/golden.md index 98ce76b5..bcd115b0 100644 --- a/test/testdata/attribute_defaults_test/golden.md +++ b/test/testdata/attribute_defaults_test/golden.md @@ -7,6 +7,8 @@ A golden test to verify attribute default values. ## my_rule+load("@stardoc//test:testdata/attribute_defaults_test/input.bzl", "my_rule") + my_rule(name, a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w)@@ -48,6 +50,8 @@ This is my rule. It does stuff. ## my_aspect+load("@stardoc//test:testdata/attribute_defaults_test/input.bzl", "my_aspect") + my_aspect(name, y, z)diff --git a/test/testdata/attribute_types_test/golden.md b/test/testdata/attribute_types_test/golden.md index 1412f2f7..d1602c98 100644 --- a/test/testdata/attribute_types_test/golden.md +++ b/test/testdata/attribute_types_test/golden.md @@ -7,6 +7,8 @@ ## my_rule+load("@stardoc//test:testdata/attribute_types_test/input.bzl", "my_rule") + my_rule(name, a, b, c, d, e, f, g, h, i, j, k, l)diff --git a/test/testdata/cc_api_test/golden.md b/test/testdata/cc_api_test/golden.md index 183402ec..df967cb6 100644 --- a/test/testdata/cc_api_test/golden.md +++ b/test/testdata/cc_api_test/golden.md @@ -7,6 +7,8 @@ Input file for C++ api test ## cpp_related_rule+load("@stardoc//test:testdata/cc_api_test/input.bzl", "cpp_related_rule") + cpp_related_rule(name, first, fourth, second, third)@@ -29,6 +31,8 @@ This rule does C++-related things. ## exercise_the_api+load("@stardoc//test:testdata/cc_api_test/input.bzl", "exercise_the_api") + exercise_the_api()@@ -41,6 +45,8 @@ exercise_the_api() ## my_rule_impl+load("@stardoc//test:testdata/cc_api_test/input.bzl", "my_rule_impl") + my_rule_impl(ctx)diff --git a/test/testdata/config_apis_test/golden.md b/test/testdata/config_apis_test/golden.md index e1d5fdfc..3c55953d 100644 --- a/test/testdata/config_apis_test/golden.md +++ b/test/testdata/config_apis_test/golden.md @@ -7,6 +7,8 @@ ## int_setting+load("@stardoc//test:testdata/config_apis_test/input.bzl", "int_setting") + int_setting(name)@@ -25,6 +27,8 @@ An integer flag. ## string_flag+load("@stardoc//test:testdata/config_apis_test/input.bzl", "string_flag") + string_flag(name)@@ -43,6 +47,8 @@ A string flag. ## exercise_the_api+load("@stardoc//test:testdata/config_apis_test/input.bzl", "exercise_the_api") + exercise_the_api()@@ -55,6 +61,8 @@ exercise_the_api() ## transition_func+load("@stardoc//test:testdata/config_apis_test/input.bzl", "transition_func") + transition_func(settings)diff --git a/test/testdata/cpp_basic_test/golden.md b/test/testdata/cpp_basic_test/golden.md index abce00a4..832d162b 100644 --- a/test/testdata/cpp_basic_test/golden.md +++ b/test/testdata/cpp_basic_test/golden.md @@ -7,6 +7,8 @@ ## cpp_related_rule+load("@stardoc//test:testdata/cpp_basic_test/input.bzl", "cpp_related_rule") + cpp_related_rule(name, first, fourth, second, third)diff --git a/test/testdata/filter_rules_test/golden.md b/test/testdata/filter_rules_test/golden.md index 2801a168..fc9badb2 100644 --- a/test/testdata/filter_rules_test/golden.md +++ b/test/testdata/filter_rules_test/golden.md @@ -7,6 +7,8 @@ ## allowlisted_dep_rule+load("@stardoc//test:testdata/filter_rules_test/input.bzl", "allowlisted_dep_rule") + allowlisted_dep_rule(name, first, second)@@ -27,6 +29,8 @@ This is the dep rule. It does stuff. ## my_rule+load("@stardoc//test:testdata/filter_rules_test/input.bzl", "my_rule") + my_rule(name, first, second)diff --git a/test/testdata/function_basic_test/golden.md b/test/testdata/function_basic_test/golden.md index bf758b18..afa5ae39 100644 --- a/test/testdata/function_basic_test/golden.md +++ b/test/testdata/function_basic_test/golden.md @@ -7,6 +7,8 @@ A test that verifies basic user function documentation. ## check_sources+load("@stardoc//test:testdata/function_basic_test/input.bzl", "check_sources") + check_sources(name, required_param, bool_param, srcs, string_param, int_param, dict_param, struct_param)@@ -37,6 +39,8 @@ Use `bazel build` to run the check. ## deprecated_do_not_use+load("@stardoc//test:testdata/function_basic_test/input.bzl", "deprecated_do_not_use") + deprecated_do_not_use()@@ -53,6 +57,8 @@ Use literally anything but this function. ## param_doc_multiline+load("@stardoc//test:testdata/function_basic_test/input.bzl", "param_doc_multiline") + param_doc_multiline(complex)@@ -71,6 +77,8 @@ Has a complex parameter. ## returns_a_thing+load("@stardoc//test:testdata/function_basic_test/input.bzl", "returns_a_thing") + returns_a_thing(name)@@ -93,6 +101,8 @@ A suffixed version of the name. ## undocumented_function+load("@stardoc//test:testdata/function_basic_test/input.bzl", "undocumented_function") + undocumented_function(a, b, c)diff --git a/test/testdata/function_wrap_multiple_lines_test/golden.md b/test/testdata/function_wrap_multiple_lines_test/golden.md index e0f2c40c..e453c029 100644 --- a/test/testdata/function_wrap_multiple_lines_test/golden.md +++ b/test/testdata/function_wrap_multiple_lines_test/golden.md @@ -7,6 +7,8 @@ Rules for ANTLR 3. ## antlr+load("@stardoc//test:testdata/function_wrap_multiple_lines_test/input.bzl", "antlr") + antlr(name, deps, srcs, Xconversiontimeout, Xdbgconversion, Xdbgst, Xdfa, Xdfaverbose, Xgrtree, Xm, Xmaxdfaedges, Xmaxinlinedfastates, Xminswitchalts, Xmultithreaded, Xnfastates, Xnocollapse, Xnomergestopstates, Xnoprune, XsaveLexer, Xwatchconversion, debug, depend, dfa, dump, imports, diff --git a/test/testdata/html_tables_template_test/golden.md b/test/testdata/html_tables_template_test/golden.md index 5ac16a81..3aa953f8 100644 --- a/test/testdata/html_tables_template_test/golden.md +++ b/test/testdata/html_tables_template_test/golden.md @@ -7,6 +7,8 @@ Input file for markdown template test ## example_rule@@ -89,6 +97,8 @@ macro_with_args_kwonly_and_kwargs(*args, name, number, **kwargs)+load("@stardoc//test:testdata/html_tables_template_test/input.bzl", "example_rule") + example_rule(name, first, second)@@ -63,6 +65,8 @@ String; optional ## ExampleProviderInfo+load("@stardoc//test:testdata/html_tables_template_test/input.bzl", "ExampleProviderInfo") + ExampleProviderInfo(foo, bar, baz)@@ -115,6 +119,8 @@ A string representing baz ## example_function+load("@stardoc//test:testdata/html_tables_template_test/input.bzl", "example_function") + example_function(foo, bar)@@ -164,6 +170,8 @@ This parameter does bar related things. ## example_aspect+load("@stardoc//test:testdata/html_tables_template_test/input.bzl", "example_aspect") + example_aspect(name, first, second)diff --git a/test/testdata/java_basic_test/golden.md b/test/testdata/java_basic_test/golden.md index e98bbd67..bc7caee7 100644 --- a/test/testdata/java_basic_test/golden.md +++ b/test/testdata/java_basic_test/golden.md @@ -7,6 +7,8 @@ ## java_related_rule+load("@stardoc//test:testdata/java_basic_test/input.bzl", "java_related_rule") + java_related_rule(name, first, fourth, second, third)diff --git a/test/testdata/local_repository_test/golden.md b/test/testdata/local_repository_test/golden.md index d06bf71e..e0c8110c 100755 --- a/test/testdata/local_repository_test/golden.md +++ b/test/testdata/local_repository_test/golden.md @@ -7,6 +7,8 @@ A test that verifies documenting functions in an input file under a local_reposi ## min+load("@local_repository_test//:input.bzl", "min") + min(integers)diff --git a/test/testdata/macro_kwargs_test/golden.md b/test/testdata/macro_kwargs_test/golden.md index c4e95cde..02f42460 100644 --- a/test/testdata/macro_kwargs_test/golden.md +++ b/test/testdata/macro_kwargs_test/golden.md @@ -7,6 +7,8 @@ Tests for functions which use *args or **kwargs ## macro_with_args+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_args") + macro_with_args(name, *args)@@ -30,6 +32,8 @@ An empty list. ## macro_with_args_and_kwonly+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_args_and_kwonly") + macro_with_args_and_kwonly(*args, name)@@ -49,6 +53,8 @@ macro_with_args_and_kwonly(*args, ## macro_with_args_and_kwonlys+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_args_and_kwonlys") + macro_with_args_and_kwonlys(*args, name, number)@@ -69,6 +75,8 @@ macro_with_args_and_kwonlys(*args +load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_args_kwonly_and_kwargs") + macro_with_args_kwonly_and_kwargs(*args, name, **kwargs)+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_kwargs") + macro_with_kwargs(name, config, deps, **kwargs)@@ -170,6 +184,8 @@ An empty list. ## macro_with_kwonly+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_kwonly") + macro_with_kwonly(*, name)@@ -188,6 +204,8 @@ One keyword-only param ## macro_with_kwonly_and_kwargs+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_kwonly_and_kwargs") + macro_with_kwonly_and_kwargs(*, name, **kwargs)@@ -207,6 +225,8 @@ One keyword-only param and **kwargs ## macro_with_kwonlys+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_kwonlys") + macro_with_kwonlys(*, name, number)@@ -226,6 +246,8 @@ Several keyword-only params ## macro_with_kwonlys_and_kwargs+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_kwonlys_and_kwargs") + macro_with_kwonlys_and_kwargs(*, name, number, **kwargs)@@ -246,6 +268,8 @@ Several keyword-only params and **kwargs ## macro_with_only_args+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_only_args") + macro_with_only_args(*args)@@ -264,6 +288,8 @@ Macro only taking *args ## macro_with_only_args_and_kwargs+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_only_args_and_kwargs") + macro_with_only_args_and_kwargs(*args, **kwargs)@@ -283,6 +309,8 @@ Macro only taking *args and **kwargs ## macro_with_only_kwargs+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_only_kwargs") + macro_with_only_kwargs(**kwargs)@@ -301,6 +329,8 @@ Macro only taking **kwargs ## macro_with_ordinary_param_and_kwonlys+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_param_and_kwonlys") + macro_with_ordinary_param_and_kwonlys(name, *, number, config)@@ -321,6 +351,8 @@ One ordinary param and several keyword-only params ## macro_with_ordinary_param_args_and_kwonlys+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_param_args_and_kwonlys") + macro_with_ordinary_param_args_and_kwonlys(name, *args, number, config)@@ -342,6 +374,8 @@ One ordinary param, *args, and several keyword-only params ## macro_with_ordinary_param_args_kwonlys_and_kwargs+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_param_args_kwonlys_and_kwargs") + macro_with_ordinary_param_args_kwonlys_and_kwargs(name, *args, number, config, **kwargs)@@ -364,6 +398,8 @@ One ordinary param, *args, several keyword-only params, and **kwargs ## macro_with_ordinary_param_kwonlys_and_kwargs+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_param_kwonlys_and_kwargs") + macro_with_ordinary_param_kwonlys_and_kwargs(name, *, number, config, **kwargs)@@ -385,6 +421,8 @@ One ordinary param, several keyword-only params, and **kwargs ## macro_with_ordinary_params_and_kwonly+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_params_and_kwonly") + macro_with_ordinary_params_and_kwonly(name, number, *, config)@@ -405,6 +443,8 @@ Several ordinary params and a keyword-only param ## macro_with_ordinary_params_args_and_kwonly+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_params_args_and_kwonly") + macro_with_ordinary_params_args_and_kwonly(name, number, *args, config)@@ -426,6 +466,8 @@ Several ordinary params, *args, and a keyword-only param ## macro_with_ordinary_params_args_kwonly_and_kwargs+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_params_args_kwonly_and_kwargs") + macro_with_ordinary_params_args_kwonly_and_kwargs(name, number, *args, config, **kwargs)@@ -448,6 +490,8 @@ Several ordinary params, *args, one keyword-only param, and **kwargs ## macro_with_ordinary_params_kwonly_and_kwargs+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_params_kwonly_and_kwargs") + macro_with_ordinary_params_kwonly_and_kwargs(name, number, *, config, **kwargs)diff --git a/test/testdata/macro_kwargs_test/legacy_golden.md b/test/testdata/macro_kwargs_test/legacy_golden.md index 0b1f0403..0aa9531f 100644 --- a/test/testdata/macro_kwargs_test/legacy_golden.md +++ b/test/testdata/macro_kwargs_test/legacy_golden.md @@ -7,6 +7,8 @@ Tests for functions which use *args or **kwargs ## macro_with_args+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_args") + macro_with_args(name, args)@@ -30,6 +32,8 @@ An empty list. ## macro_with_args_and_kwonly+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_args_and_kwonly") + macro_with_args_and_kwonly(name, args)@@ -49,6 +53,8 @@ macro_with_args_and_kwonly(name, ## macro_with_args_and_kwonlys+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_args_and_kwonlys") + macro_with_args_and_kwonlys(name, number, args)@@ -69,6 +75,8 @@ macro_with_args_and_kwonlys(name ## macro_with_args_kwonly_and_kwargs+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_args_kwonly_and_kwargs") + macro_with_args_kwonly_and_kwargs(name, args, kwargs)@@ -89,6 +97,8 @@ macro_with_args_kwonly_and_kwargs(name, number, args, kwargs)
+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_kwargs") + macro_with_kwargs(name, config, deps, kwargs)@@ -170,6 +184,8 @@ An empty list. ## macro_with_kwonly
+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_kwonly") + macro_with_kwonly(name)@@ -188,6 +204,8 @@ One keyword-only param ## macro_with_kwonly_and_kwargs
+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_kwonly_and_kwargs") + macro_with_kwonly_and_kwargs(name, kwargs)@@ -207,6 +225,8 @@ One keyword-only param and **kwargs ## macro_with_kwonlys
+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_kwonlys") + macro_with_kwonlys(name, number)@@ -226,6 +246,8 @@ Several keyword-only params ## macro_with_kwonlys_and_kwargs
+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_kwonlys_and_kwargs") + macro_with_kwonlys_and_kwargs(name, number, kwargs)@@ -246,6 +268,8 @@ Several keyword-only params and **kwargs ## macro_with_only_args
+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_only_args") + macro_with_only_args(args)@@ -264,6 +288,8 @@ Macro only taking *args ## macro_with_only_args_and_kwargs
+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_only_args_and_kwargs") + macro_with_only_args_and_kwargs(args, kwargs)@@ -283,6 +309,8 @@ Macro only taking *args and **kwargs ## macro_with_only_kwargs
+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_only_kwargs") + macro_with_only_kwargs(kwargs)@@ -301,6 +329,8 @@ Macro only taking **kwargs ## macro_with_ordinary_param_and_kwonlys
+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_param_and_kwonlys") + macro_with_ordinary_param_and_kwonlys(name, number, config)@@ -321,6 +351,8 @@ One ordinary param and several keyword-only params ## macro_with_ordinary_param_args_and_kwonlys
+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_param_args_and_kwonlys") + macro_with_ordinary_param_args_and_kwonlys(name, number, config, args)@@ -342,6 +374,8 @@ One ordinary param, *args, and several keyword-only params ## macro_with_ordinary_param_args_kwonlys_and_kwargs
+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_param_args_kwonlys_and_kwargs") + macro_with_ordinary_param_args_kwonlys_and_kwargs(name, number, config, args, kwargs)@@ -364,6 +398,8 @@ One ordinary param, *args, several keyword-only params, and **kwargs ## macro_with_ordinary_param_kwonlys_and_kwargs
+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_param_kwonlys_and_kwargs") + macro_with_ordinary_param_kwonlys_and_kwargs(name, number, config, kwargs)@@ -385,6 +421,8 @@ One ordinary param, several keyword-only params, and **kwargs ## macro_with_ordinary_params_and_kwonly
+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_params_and_kwonly") + macro_with_ordinary_params_and_kwonly(name, number, config)@@ -405,6 +443,8 @@ Several ordinary params and a keyword-only param ## macro_with_ordinary_params_args_and_kwonly
+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_params_args_and_kwonly") + macro_with_ordinary_params_args_and_kwonly(name, number, config, args)@@ -426,6 +466,8 @@ Several ordinary params, *args, and a keyword-only param ## macro_with_ordinary_params_args_kwonly_and_kwargs
+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_params_args_kwonly_and_kwargs") + macro_with_ordinary_params_args_kwonly_and_kwargs(name, number, config, args, kwargs)@@ -448,6 +490,8 @@ Several ordinary params, *args, one keyword-only param, and **kwargs ## macro_with_ordinary_params_kwonly_and_kwargs
+load("@stardoc//test:testdata/macro_kwargs_test/input.bzl", "macro_with_ordinary_params_kwonly_and_kwargs") + macro_with_ordinary_params_kwonly_and_kwargs(name, number, config, kwargs)diff --git a/test/testdata/misc_apis_test/golden.md b/test/testdata/misc_apis_test/golden.md index 4368d437..6a311cc7 100644 --- a/test/testdata/misc_apis_test/golden.md +++ b/test/testdata/misc_apis_test/golden.md @@ -7,6 +7,8 @@ ## my_rule
+load("@stardoc//test:testdata/misc_apis_test/input.bzl", "my_rule") + my_rule(name, deps, src, out, extra_arguments, tool)@@ -30,6 +32,8 @@ This rule exercises some of the build API. ## MyInfo
+load("@stardoc//test:testdata/misc_apis_test/input.bzl", "MyInfo") + MyInfo(foo, bar)@@ -46,6 +50,8 @@ MyInfo(foo, bar) ## exercise_the_api
+load("@stardoc//test:testdata/misc_apis_test/input.bzl", "exercise_the_api") + exercise_the_api()@@ -58,6 +64,8 @@ exercise_the_api() ## my_rule_impl
+load("@stardoc//test:testdata/misc_apis_test/input.bzl", "my_rule_impl") + my_rule_impl(ctx)diff --git a/test/testdata/multi_level_namespace_test/golden.md b/test/testdata/multi_level_namespace_test/golden.md index 3e753c08..ba65c5ba 100644 --- a/test/testdata/multi_level_namespace_test/golden.md +++ b/test/testdata/multi_level_namespace_test/golden.md @@ -7,6 +7,8 @@ A test that verifies documenting a multi-leveled namespace of functions. ## my_namespace.foo.bar.baz
+load("@stardoc//test:testdata/multi_level_namespace_test/input.bzl", "my_namespace") + my_namespace.foo.bar.baz()@@ -19,6 +21,8 @@ This function does nothing. ## my_namespace.math.min
+load("@stardoc//test:testdata/multi_level_namespace_test/input.bzl", "my_namespace") + my_namespace.math.min(integers)@@ -41,6 +45,8 @@ The minimum integer in the given list. ## my_namespace.min
+load("@stardoc//test:testdata/multi_level_namespace_test/input.bzl", "my_namespace") + my_namespace.min(integers)@@ -63,6 +69,8 @@ The minimum integer in the given list. ## my_namespace.one.three.does_nothing
+load("@stardoc//test:testdata/multi_level_namespace_test/input.bzl", "my_namespace") + my_namespace.one.three.does_nothing()@@ -75,6 +83,8 @@ This function does nothing. ## my_namespace.one.two.min
+load("@stardoc//test:testdata/multi_level_namespace_test/input.bzl", "my_namespace") + my_namespace.one.two.min(integers)diff --git a/test/testdata/multi_level_namespace_test_with_allowlist/golden.md b/test/testdata/multi_level_namespace_test_with_allowlist/golden.md index f35b10d2..2e4a52eb 100644 --- a/test/testdata/multi_level_namespace_test_with_allowlist/golden.md +++ b/test/testdata/multi_level_namespace_test_with_allowlist/golden.md @@ -9,6 +9,8 @@ specific symbol in other_namespace to be documented. ## my_namespace.math.min
+load("@stardoc//test:testdata/multi_level_namespace_test_with_allowlist/input.bzl", "my_namespace") + my_namespace.math.min(integers)@@ -27,6 +29,8 @@ Returns the minimum of given elements. ## my_namespace.min
+load("@stardoc//test:testdata/multi_level_namespace_test_with_allowlist/input.bzl", "my_namespace") + my_namespace.min(integers)@@ -45,6 +49,8 @@ Returns the minimum of given elements. ## other_namespace.foo.nothing
+load("@stardoc//test:testdata/multi_level_namespace_test_with_allowlist/input.bzl", "other_namespace") + other_namespace.foo.nothing()diff --git a/test/testdata/multiple_files_test/golden.md b/test/testdata/multiple_files_test/golden.md index 0fab337a..8fe32598 100644 --- a/test/testdata/multiple_files_test/golden.md +++ b/test/testdata/multiple_files_test/golden.md @@ -7,6 +7,8 @@ A direct dependency file of the input file. ## my_rule
+load("@stardoc//test:testdata/multiple_files_test/input.bzl", "my_rule") + my_rule(name, first, second)@@ -27,6 +29,8 @@ This is my rule. It does stuff. ## other_rule
+load("@stardoc//test:testdata/multiple_files_test/input.bzl", "other_rule") + other_rule(name, fourth, third)@@ -47,6 +51,8 @@ This is another rule. ## yet_another_rule
+load("@stardoc//test:testdata/multiple_files_test/input.bzl", "yet_another_rule") + yet_another_rule(name, fifth)@@ -66,6 +72,8 @@ This is yet another rule ## top_fun
+load("@stardoc//test:testdata/multiple_files_test/input.bzl", "top_fun") + top_fun(a, b, c)diff --git a/test/testdata/multiple_files_test/noenable_bzlmod_golden.md b/test/testdata/multiple_files_test/noenable_bzlmod_golden.md new file mode 100644 index 00000000..3903b308 --- /dev/null +++ b/test/testdata/multiple_files_test/noenable_bzlmod_golden.md @@ -0,0 +1,91 @@ + + +A direct dependency file of the input file. + + + +## my_rule + +
+load("@io_bazel_stardoc//test:testdata/multiple_files_test/input.bzl", "my_rule") + +my_rule(name, first, second) ++ +This is my rule. It does stuff. + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this target. | Name | required | | +| first | first my_rule doc string | Label | required | | +| second | - | Dictionary: String -> String | required | | + + + + +## other_rule + +
+load("@io_bazel_stardoc//test:testdata/multiple_files_test/input.bzl", "other_rule") + +other_rule(name, fourth, third) ++ +This is another rule. + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this target. | Name | required | | +| fourth | - | Dictionary: String -> String | required | | +| third | third other_rule doc string | Label | required | | + + + + +## yet_another_rule + +
+load("@io_bazel_stardoc//test:testdata/multiple_files_test/input.bzl", "yet_another_rule") + +yet_another_rule(name, fifth) ++ +This is yet another rule + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this target. | Name | required | | +| fifth | - | Label | required | | + + + + +## top_fun + +
+load("@io_bazel_stardoc//test:testdata/multiple_files_test/input.bzl", "top_fun") + +top_fun(a, b, c) ++ + + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| a |
-
| none | +| b |-
| none | +| c |-
| none | + + diff --git a/test/testdata/multiple_rules_test/golden.md b/test/testdata/multiple_rules_test/golden.md index 085fec81..fa470fc4 100644 --- a/test/testdata/multiple_rules_test/golden.md +++ b/test/testdata/multiple_rules_test/golden.md @@ -7,6 +7,8 @@ ## my_rule+load("@stardoc//test:testdata/multiple_rules_test/input.bzl", "my_rule") + my_rule(name, first, second)@@ -27,6 +29,8 @@ This is my rule. It does stuff. ## other_rule
+load("@stardoc//test:testdata/multiple_rules_test/input.bzl", "other_rule") + other_rule(name, fourth, third)@@ -47,6 +51,8 @@ This is another rule. ## yet_another_rule
+load("@stardoc//test:testdata/multiple_rules_test/input.bzl", "yet_another_rule") + yet_another_rule(name, fifth)@@ -66,6 +72,8 @@ This is yet another rule ## my_rule_impl
+load("@stardoc//test:testdata/multiple_rules_test/input.bzl", "my_rule_impl") + my_rule_impl(ctx)diff --git a/test/testdata/namespace_test/golden.md b/test/testdata/namespace_test/golden.md index 6e4c453d..a8ee42eb 100644 --- a/test/testdata/namespace_test/golden.md +++ b/test/testdata/namespace_test/golden.md @@ -7,6 +7,8 @@ A test that verifies documenting a namespace of functions. ## my_namespace.assert_non_empty
+load("@stardoc//test:testdata/namespace_test/input.bzl", "my_namespace") + my_namespace.assert_non_empty(some_list, other_list)@@ -26,6 +28,8 @@ Asserts the two given lists are not empty. ## my_namespace.join_strings
+load("@stardoc//test:testdata/namespace_test/input.bzl", "my_namespace") + my_namespace.join_strings(strings, delimiter)@@ -49,6 +53,8 @@ The joined string. ## my_namespace.min
+load("@stardoc//test:testdata/namespace_test/input.bzl", "my_namespace") + my_namespace.min(integers)diff --git a/test/testdata/provider_basic_test/golden.md b/test/testdata/provider_basic_test/golden.md index ec94c4aa..29979b36 100644 --- a/test/testdata/provider_basic_test/golden.md +++ b/test/testdata/provider_basic_test/golden.md @@ -7,6 +7,8 @@ ## MyCustomInitInfo
+load("@stardoc//test:testdata/provider_basic_test/input.bzl", "MyCustomInitInfo") + MyCustomInitInfo(foo, bar)@@ -28,6 +30,8 @@ we don't need to render a separate table of constructor parameters. ## MyCustomInitWithDefaultParamValueInfo
+load("@stardoc//test:testdata/provider_basic_test/input.bzl", "MyCustomInitWithDefaultParamValueInfo") + MyCustomInitWithDefaultParamValueInfo(foo, bar)@@ -50,6 +54,8 @@ we do need to render the default value. ## MyCustomInitWithDocumentedParamInfo
+load("@stardoc//test:testdata/provider_basic_test/input.bzl", "MyCustomInitWithDocumentedParamInfo") + MyCustomInitWithDocumentedParamInfo(foo, bar)@@ -78,6 +84,8 @@ constructor parameters as a separate table. ## MyCustomInitWithMismatchingConstructorParamsAndFieldsInfo
+load("@stardoc//test:testdata/provider_basic_test/input.bzl", "MyCustomInitWithMismatchingConstructorParamsAndFieldsInfo") + MyCustomInitWithMismatchingConstructorParamsAndFieldsInfo(foo, bar)@@ -106,6 +114,8 @@ We have no choice - we need to render constructor parameters as a separate table ## MyDeprecatedInfo
+load("@stardoc//test:testdata/provider_basic_test/input.bzl", "MyDeprecatedInfo") + MyDeprecatedInfo()@@ -129,6 +139,8 @@ Do not construct! ## MyFooInfo
+load("@stardoc//test:testdata/provider_basic_test/input.bzl", "MyFooInfo") + MyFooInfo(bar, baz)@@ -147,6 +159,8 @@ Stores information about a foo. ## MyPoorlyDocumentedInfo
+load("@stardoc//test:testdata/provider_basic_test/input.bzl", "MyPoorlyDocumentedInfo") + MyPoorlyDocumentedInfo()@@ -156,6 +170,8 @@ MyPoorlyDocumentedInfo() ## MyVeryDocumentedInfo
+load("@stardoc//test:testdata/provider_basic_test/input.bzl", "MyVeryDocumentedInfo") + MyVeryDocumentedInfo(favorite_food, favorite_color)diff --git a/test/testdata/providers_for_attributes_test/golden.md b/test/testdata/providers_for_attributes_test/golden.md index b2599961..a583c6f5 100644 --- a/test/testdata/providers_for_attributes_test/golden.md +++ b/test/testdata/providers_for_attributes_test/golden.md @@ -7,6 +7,8 @@ The input file for the providers for attributes test ## my_rule
+load("@stardoc//test:testdata/providers_for_attributes_test/input.bzl", "my_rule") + my_rule(name, fifth, first, fourth, second, sixth, third)@@ -31,6 +33,8 @@ This rule does things. ## MyProviderInfo
+load("@stardoc//test:testdata/providers_for_attributes_test/input.bzl", "MyProviderInfo") + MyProviderInfo(foo, bar)@@ -47,6 +51,8 @@ MyProviderInfo(foo, @@ -56,6 +62,8 @@ OtherProviderInfo() ## my_rule_impl
+load("@stardoc//test:testdata/providers_for_attributes_test/input.bzl", "my_rule_impl") + my_rule_impl(ctx)diff --git a/test/testdata/pure_markdown_template_test/golden.md b/test/testdata/pure_markdown_template_test/golden.md index d39dbb58..96e47afb 100644 --- a/test/testdata/pure_markdown_template_test/golden.md +++ b/test/testdata/pure_markdown_template_test/golden.md @@ -7,6 +7,8 @@ Input file for markdown template test ## example_rule
+load("@stardoc//test:testdata/pure_markdown_template_test/input.bzl", "example_rule") + example_rule(name, first, second)@@ -27,6 +29,8 @@ Small example of rule using a markdown template. ## ExampleProviderInfo
+load("@stardoc//test:testdata/pure_markdown_template_test/input.bzl", "ExampleProviderInfo") + ExampleProviderInfo(foo, bar, baz)@@ -46,6 +50,8 @@ Small example of provider using a markdown template. ## example_function
+load("@stardoc//test:testdata/pure_markdown_template_test/input.bzl", "example_function") + example_function(foo, bar)@@ -65,6 +71,8 @@ Small example of function using a markdown template. ## example_aspect
+load("@stardoc//test:testdata/pure_markdown_template_test/input.bzl", "example_aspect") + example_aspect(name, first, second)diff --git a/test/testdata/py_rule_test/golden.md b/test/testdata/py_rule_test/golden.md index d2a83942..6a37594c 100644 --- a/test/testdata/py_rule_test/golden.md +++ b/test/testdata/py_rule_test/golden.md @@ -7,6 +7,8 @@ The input file for the python rule test ## py_related_rule
+load("@stardoc//test:testdata/py_rule_test/input.bzl", "py_related_rule") + py_related_rule(name, fifth, first, fourth, second, sixth, third)diff --git a/test/testdata/repo_rules_test/golden.md b/test/testdata/repo_rules_test/golden.md index ac434151..e3979f1d 100644 --- a/test/testdata/repo_rules_test/golden.md +++ b/test/testdata/repo_rules_test/golden.md @@ -7,6 +7,8 @@ ## my_repo
+load("@stardoc//test:testdata/repo_rules_test/input.bzl", "my_repo") + my_repo(name, repo_mapping, useless)diff --git a/test/testdata/same_level_file_test/BUILD b/test/testdata/same_level_file_test/BUILD index 0f4f48a9..d5ef45ea 100644 --- a/test/testdata/same_level_file_test/BUILD +++ b/test/testdata/same_level_file_test/BUILD @@ -9,6 +9,7 @@ exports_files( [ "dep.bzl", "golden.md", + "noenable_bzlmod_golden.md", "input.bzl", ], ) diff --git a/test/testdata/same_level_file_test/golden.md b/test/testdata/same_level_file_test/golden.md index 66b9a978..d4761bfa 100644 --- a/test/testdata/same_level_file_test/golden.md +++ b/test/testdata/same_level_file_test/golden.md @@ -7,6 +7,8 @@ ## my_rule
+load("@stardoc//test/testdata/same_level_file_test:input.bzl", "my_rule") + my_rule(name, first, second)diff --git a/test/testdata/same_level_file_test/noenable_bzlmod_golden.md b/test/testdata/same_level_file_test/noenable_bzlmod_golden.md new file mode 100644 index 00000000..e7870e72 --- /dev/null +++ b/test/testdata/same_level_file_test/noenable_bzlmod_golden.md @@ -0,0 +1,26 @@ + + + + + + +## my_rule + +
+load("@io_bazel_stardoc//test/testdata/same_level_file_test:input.bzl", "my_rule") + +my_rule(name, first, second) ++ +This is my rule. It does stuff. + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this target. | Name | required | | +| first | first my_rule doc string | Label | required | | +| second | - | Dictionary: String -> String | required | | + + diff --git a/test/testdata/simple_test/golden.md b/test/testdata/simple_test/golden.md index a5a2e395..8f7456a0 100644 --- a/test/testdata/simple_test/golden.md +++ b/test/testdata/simple_test/golden.md @@ -7,6 +7,8 @@ ## my_rule
+load("@stardoc//test:testdata/simple_test/input.bzl", "my_rule") + my_rule(name, first, fourth, second, third)diff --git a/test/testdata/struct_default_value_test/golden.md b/test/testdata/struct_default_value_test/golden.md index 38f9908c..3260c2ad 100644 --- a/test/testdata/struct_default_value_test/golden.md +++ b/test/testdata/struct_default_value_test/golden.md @@ -7,6 +7,8 @@ The input file for struct default values test ## check_struct_default_values
+load("@stardoc//test:testdata/struct_default_value_test/input.bzl", "check_struct_default_values") + check_struct_default_values(struct_no_args, struct_arg, struct_args, struct_int_args, struct_struct_args)diff --git a/test/testdata/table_of_contents_test/golden.md b/test/testdata/table_of_contents_test/golden.md index a49b49c0..cc2da345 100644 --- a/test/testdata/table_of_contents_test/golden.md +++ b/test/testdata/table_of_contents_test/golden.md @@ -36,6 +36,8 @@ Test rules / providers / etc for the table of contents generation test. ## my_rule
+load("@stardoc//test:testdata/table_of_contents_test/input.bzl", "my_rule") + my_rule(name, first, fourth, second, third)@@ -58,6 +60,8 @@ This is my rule. It does stuff. ## MyFooInfo
+load("@stardoc//test:testdata/table_of_contents_test/input.bzl", "MyFooInfo") + MyFooInfo(bar, baz)@@ -76,6 +80,8 @@ Stores information about a foo. ## MyVeryDocumentedInfo
+load("@stardoc//test:testdata/table_of_contents_test/input.bzl", "MyVeryDocumentedInfo") + MyVeryDocumentedInfo(favorite_food, favorite_color)@@ -96,6 +102,8 @@ Look on my works, ye mighty, and despair! ## check_sources
+load("@stardoc//test:testdata/table_of_contents_test/input.bzl", "check_sources") + check_sources(name, required_param, bool_param, srcs, string_param, int_param, dict_param, struct_param)@@ -126,6 +134,8 @@ Use `bazel build` to run the check. ## returns_a_thing
+load("@stardoc//test:testdata/table_of_contents_test/input.bzl", "returns_a_thing") + returns_a_thing(name)@@ -148,6 +158,8 @@ A suffixed version of the name. ## my_aspect
+load("@stardoc//test:testdata/table_of_contents_test/input.bzl", "my_aspect") + my_aspect(name, first, second)@@ -179,6 +191,8 @@ It does stuff. ## other_aspect
+load("@stardoc//test:testdata/table_of_contents_test/input.bzl", "other_aspect") + other_aspect(name, third)@@ -202,6 +216,8 @@ This is another aspect. ## my_repo
+load("@stardoc//test:testdata/table_of_contents_test/input.bzl", "my_repo") + my_repo(name, repo_mapping, useless)diff --git a/test/testdata/table_of_contents_test/noenable_bzlmod_golden.md b/test/testdata/table_of_contents_test/noenable_bzlmod_golden.md new file mode 100644 index 00000000..5039f2c7 --- /dev/null +++ b/test/testdata/table_of_contents_test/noenable_bzlmod_golden.md @@ -0,0 +1,283 @@ + + +Test rules / providers / etc for the table of contents generation test. + + +## Rules + +- [my_rule](#my_rule) + +## Providers + +- [MyFooInfo](#MyFooInfo) +- [MyVeryDocumentedInfo](#MyVeryDocumentedInfo) + +## Functions + +- [check_sources](#check_sources) +- [returns_a_thing](#returns_a_thing) + +## Aspects + +- [my_aspect](#my_aspect) +- [other_aspect](#other_aspect) + +## Repository Rules + +- [my_repo](#my_repo) + +## Module Extensions + +- [my_ext](#my_ext) + + + + +## my_rule + +
+load("@io_bazel_stardoc//test:testdata/table_of_contents_test/input.bzl", "my_rule") + +my_rule(name, first, fourth, second, third) ++ +This is my rule. It does stuff. + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this target. | Name | required | | +| first | first doc string | Label | required | | +| fourth | fourth doc string | Boolean | optional | `False` | +| second | - | Dictionary: String -> String | required | | +| third | - | Label | required | | + + + + +## MyFooInfo + +
+load("@io_bazel_stardoc//test:testdata/table_of_contents_test/input.bzl", "MyFooInfo") + +MyFooInfo(bar, baz) ++ +Stores information about a foo. + +**FIELDS** + +| Name | Description | +| :------------- | :------------- | +| bar | - | +| baz | - | + + + + +## MyVeryDocumentedInfo + +
+load("@io_bazel_stardoc//test:testdata/table_of_contents_test/input.bzl", "MyVeryDocumentedInfo") + +MyVeryDocumentedInfo(favorite_food, favorite_color) ++ +A provider with some really neat documentation. + +Look on my works, ye mighty, and despair! + +**FIELDS** + +| Name | Description | +| :------------- | :------------- | +| favorite_food | A string representing my favorite food
+load("@io_bazel_stardoc//test:testdata/table_of_contents_test/input.bzl", "check_sources") + +check_sources(name, required_param, bool_param, srcs, string_param, int_param, dict_param, + struct_param) ++ +Runs some checks on the given source files. + +This rule runs checks on a given set of source files. +Use `bazel build` to run the check. + + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| name | A unique name for this rule. | none | +| required_param | Use your imagination. | none | +| bool_param |
-
| `True` | +| srcs | Source files to run the checks against. | `[]` | +| string_param |-
| `""` | +| int_param | Your favorite number. | `2` | +| dict_param |-
| `{}` | +| struct_param |-
| `struct(foo = "bar")` | + + + + +## returns_a_thing + ++load("@io_bazel_stardoc//test:testdata/table_of_contents_test/input.bzl", "returns_a_thing") + +returns_a_thing(name) ++ +Returns a suffixed name. + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| name | A unique name for this rule. | none | + +**RETURNS** + +A suffixed version of the name. + + + + +## my_aspect + +
+load("@io_bazel_stardoc//test:testdata/table_of_contents_test/input.bzl", "my_aspect") + +my_aspect(name, first, second) ++ +This is my aspect. + +It does stuff. + +**ASPECT ATTRIBUTES** + + +| Name | Type | +| :------------- | :------------- | +| deps| String | +| attr_aspect| String | + + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this target. | Name | required | | +| first | - | Boolean | required | | +| second | - | String | required | | + + + + +## other_aspect + +
+load("@io_bazel_stardoc//test:testdata/table_of_contents_test/input.bzl", "other_aspect") + +other_aspect(name, third) ++ +This is another aspect. + +**ASPECT ATTRIBUTES** + + + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this target. | Name | required | | +| third | - | Integer | required | | + + + + +## my_repo + +
+load("@io_bazel_stardoc//test:testdata/table_of_contents_test/input.bzl", "my_repo") + +my_repo(name, repo_mapping, useless) ++ +Minimal example of a repository rule. + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this repository. | Name | required | | +| repo_mapping | In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.
+my_ext = use_extension("@io_bazel_stardoc//test:testdata/table_of_contents_test/input.bzl", "my_ext") +my_ext.install(artifacts) +my_ext.artifact(artifact, group) ++ +Minimal example of a module extension. + + +**TAG CLASSES** + + + +### install + +Install tag + +**Attributes** + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| artifacts | Install artifacts | List of strings | optional | `[]` | + + + +### artifact + +Artifact tag + +**Attributes** + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| artifact | Artifact | String | required | | +| group | Group name | String | optional | `"my_group"` | + + diff --git a/test/testdata/unknown_name_test/golden.md b/test/testdata/unknown_name_test/golden.md index 8bbe43c9..add5ea90 100644 --- a/test/testdata/unknown_name_test/golden.md +++ b/test/testdata/unknown_name_test/golden.md @@ -7,6 +7,8 @@ ## my_rule_impl
+load("@stardoc//test:testdata/unknown_name_test/input.bzl", "my_rule_impl") + my_rule_impl(ctx)diff --git a/update-stardoc-tests.sh b/update-stardoc-tests.sh index 9d45698a..ca9a7f7f 100755 --- a/update-stardoc-tests.sh +++ b/update-stardoc-tests.sh @@ -39,19 +39,20 @@ function update_non_manual_tests () { function update_manual_tests_with_tag () { local manual_tag="$1"; shift - echo "** Querying for tests tagged \"${manual_tag}\", \"manual\" using 'USE_BAZEL_VERSION=${USE_BAZEL_VERSION} ${BAZEL}' ..." - regenerate $(${BAZEL} query "attr(tags, ${manual_tag}, attr(tags, manual, kind(sh_binary, //test:all)))" | grep _regenerate) + echo "** Querying for tests tagged \"${manual_tag}\", \"manual\" using 'USE_BAZEL_VERSION=${USE_BAZEL_VERSION:-} ${BAZEL}' $@ ..." + BUILD_FLAGS="$@" regenerate $(${BAZEL} query "attr(tags, ${manual_tag}, attr(tags, manual, kind(sh_binary, //test:all)))" | grep _regenerate) } function regenerate () { echo "** Regenerating and copying goldens..." + local run_cmd="run ${BUILD_FLAGS:-}" for regen_target in $@; do - if [[ -z ${USE_BAZEL_VERSION+x} ]]; then - echo "** Running '${BAZEL} run ${regen_target}' ..." + if [[ -z ${USE_BAZEL_VERSION:-} ]]; then + echo "** Running '${BAZEL} ${run_cmd} ${regen_target}' ..." else - echo "** Running 'USE_BAZEL_VERSION=${USE_BAZEL_VERSION} ${BAZEL} run ${regen_target}' ..." + echo "** Running 'USE_BAZEL_VERSION=${USE_BAZEL_VERSION} ${BAZEL} ${run_cmd} ${regen_target}' BAZEL_BUILD_FLAGS ..." fi - ${BAZEL} run "${regen_target}" + ${BAZEL} ${run_cmd} "${regen_target}" done } @@ -59,6 +60,7 @@ function regenerate () { : "${BAZEL:=bazelisk}" update_non_manual_tests +update_manual_tests_with_tag "noenable_bzlmod" --noenable_bzlmod USE_BAZEL_VERSION="7.2.0" update_manual_tests_with_tag "bazel_7_2" USE_BAZEL_VERSION="8.0.0-pre.20240603.2" update_manual_tests_with_tag "bazel_8"