Enable render_main_repo_name by default with starlark_doc_extract (#168)

Most Stardoc users are probably documenting their rules for users from other repos - so we ought to render labels in the repo being documented with the repo name.

docs/stardoc_rule.md

@@ -9,7 +9,8 @@ Starlark rule for stardoc: a documentation generator tool written in Java.
 <pre>
 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-semantic_flags">semantic_flags</a>, <a href="#stardoc-stardoc">stardoc</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-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-use_starlark_doc_extract">use_starlark_doc_extract</a>, <a href="#stardoc-kwargs">kwargs</a>)
+        <a href="#stardoc-repository_rule_template">repository_rule_template</a>, <a href="#stardoc-module_extension_template">module_extension_template</a>, <a href="#stardoc-use_starlark_doc_extract">use_starlark_doc_extract</a>,
+        <a href="#stardoc-render_main_repo_name">render_main_repo_name</a>, <a href="#stardoc-kwargs">kwargs</a>)
 </pre>
 
 Generates documentation for exported starlark rule definitions in a target starlark file.
@@ -26,16 +27,17 @@ Generates documentation for exported starlark rule definitions in a target starl
 | <a id="stardoc-format"></a>format |  The format of the output file. Valid values: 'markdown' or 'proto'.   |  `"markdown"` |
 | <a id="stardoc-symbol_names"></a>symbol_names |  A list of symbol names to generate documentation for. These should correspond to the names of rule definitions in the input file. If this list is empty, then documentation for all exported rule definitions will be generated.   |  `[]` |
 | <a id="stardoc-semantic_flags"></a>semantic_flags |  A list of canonical flags to affect Starlark semantics for the Starlark interpreter during documentation generation. This should only be used to maintain compatibility with non-default semantic flags required to use the given Starlark symbols.<br><br>For example, if `//foo:bar.bzl` does not build except when a user would specify `--incompatible_foo_semantic=false`, then this attribute should contain "--incompatible_foo_semantic=false".   |  `[]` |
-| <a id="stardoc-stardoc"></a>stardoc |  The location of the legacy Stardoc extractor. Ignored when using the native `starlark_doc_extract` rule.   |  `Label("//stardoc:prebuilt_stardoc_binary")` |
-| <a id="stardoc-renderer"></a>renderer |  The location of the renderer tool.   |  `Label("//stardoc:renderer")` |
-| <a id="stardoc-aspect_template"></a>aspect_template |  The input file template for generating documentation of aspects   |  `Label("//stardoc:templates/markdown_tables/aspect.vm")` |
-| <a id="stardoc-func_template"></a>func_template |  The input file template for generating documentation of functions.   |  `Label("//stardoc:templates/markdown_tables/func.vm")` |
-| <a id="stardoc-header_template"></a>header_template |  The input file template for the header of the output documentation.   |  `Label("//stardoc:templates/markdown_tables/header.vm")` |
-| <a id="stardoc-provider_template"></a>provider_template |  The input file template for generating documentation of providers.   |  `Label("//stardoc:templates/markdown_tables/provider.vm")` |
-| <a id="stardoc-rule_template"></a>rule_template |  The input file template for generating documentation of rules.   |  `Label("//stardoc:templates/markdown_tables/rule.vm")` |
-| <a id="stardoc-repository_rule_template"></a>repository_rule_template |  The input file template for generating documentation of repository rules. This template is used only when using the native `starlark_doc_extract` rule.   |  `Label("//stardoc:templates/markdown_tables/repository_rule.vm")` |
-| <a id="stardoc-module_extension_template"></a>module_extension_template |  The input file template for generating documentation of module extensions. This template is used only when using the native `starlark_doc_extract` rule.   |  `Label("//stardoc:templates/markdown_tables/module_extension.vm")` |
+| <a id="stardoc-stardoc"></a>stardoc |  The location of the legacy Stardoc extractor. Ignored when using the native `starlark_doc_extract` rule.   |  `Label("@io_bazel_stardoc//stardoc:prebuilt_stardoc_binary")` |
+| <a id="stardoc-renderer"></a>renderer |  The location of the renderer tool.   |  `Label("@io_bazel_stardoc//stardoc:renderer")` |
+| <a id="stardoc-aspect_template"></a>aspect_template |  The input file template for generating documentation of aspects   |  `Label("@io_bazel_stardoc//stardoc:templates/markdown_tables/aspect.vm")` |
+| <a id="stardoc-func_template"></a>func_template |  The input file template for generating documentation of functions.   |  `Label("@io_bazel_stardoc//stardoc:templates/markdown_tables/func.vm")` |
+| <a id="stardoc-header_template"></a>header_template |  The input file template for the header of the output documentation.   |  `Label("@io_bazel_stardoc//stardoc:templates/markdown_tables/header.vm")` |
+| <a id="stardoc-provider_template"></a>provider_template |  The input file template for generating documentation of providers.   |  `Label("@io_bazel_stardoc//stardoc:templates/markdown_tables/provider.vm")` |
+| <a id="stardoc-rule_template"></a>rule_template |  The input file template for generating documentation of rules.   |  `Label("@io_bazel_stardoc//stardoc:templates/markdown_tables/rule.vm")` |
+| <a id="stardoc-repository_rule_template"></a>repository_rule_template |  The input file template for generating documentation of repository rules. This template is used only when using the native `starlark_doc_extract` rule.   |  `Label("@io_bazel_stardoc//stardoc:templates/markdown_tables/repository_rule.vm")` |
+| <a id="stardoc-module_extension_template"></a>module_extension_template |  The input file template for generating documentation of module extensions. This template is used only when using the native `starlark_doc_extract` rule.   |  `Label("@io_bazel_stardoc//stardoc:templates/markdown_tables/module_extension.vm")` |
 | <a id="stardoc-use_starlark_doc_extract"></a>use_starlark_doc_extract |  Use the native `starlark_doc_extract` rule if available.   |  `True` |
+| <a id="stardoc-render_main_repo_name"></a>render_main_repo_name |  Render labels in the main repository with a repo component (either the module name or workspace name). This parameter is used only when using the native `starlark_doc_extract` rule.   |  `True` |
 | <a id="stardoc-kwargs"></a>kwargs |  Further arguments to pass to stardoc.   |  none |
 
 

stardoc/stardoc.bzl

@@ -37,6 +37,7 @@ def stardoc(
         repository_rule_template = Label("//stardoc:templates/markdown_tables/repository_rule.vm"),
         module_extension_template = Label("//stardoc:templates/markdown_tables/module_extension.vm"),
         use_starlark_doc_extract = True,
+        render_main_repo_name = True,
         **kwargs):
     """Generates documentation for exported starlark rule definitions in a target starlark file.
 
@@ -67,6 +68,9 @@ def stardoc(
         This template is used only when using the native `starlark_doc_extract` rule.
       module_extension_template: The input file template for generating documentation of module extensions.
         This template is used only when using the native `starlark_doc_extract` rule.
+      render_main_repo_name: Render labels in the main repository with a repo component (either
+        the module name or workspace name). This parameter is used only when using the native
+        `starlark_doc_extract` rule.
       use_starlark_doc_extract: Use the native `starlark_doc_extract` rule if available.
       **kwargs: Further arguments to pass to stardoc.
     """
@@ -96,6 +100,7 @@ def stardoc(
             name = extractor_name,
             src = input,
             deps = deps,
+            render_main_repo_name = render_main_repo_name,
             symbol_names = symbol_names,
             **(kwargs if extractor_is_main_target else auxiliary_target_kwargs)
         )

test/BUILD

@@ -1,20 +1,14 @@
-load(":stardoc_test.bzl", "stardoc_test")
+load(":stardoc_test.bzl", "self_gen_test", "stardoc_test")
 
 package(default_applicable_licenses = ["//:license"])
 
 licenses(["notice"])  # Apache 2.0
 
-sh_test(
+self_gen_test(
     name = "stardoc_self_gen_test",
-    srcs = ["diff_test_runner.sh"],
-    args = [
-        "$(location //stardoc:stardoc_doc.md)",
-        "$(location //:stardoc_rule_doc)",
-    ],
-    data = [
-        "//:stardoc_rule_doc",
-        "//stardoc:stardoc_doc.md",
-    ],
+    golden_file = "//stardoc:stardoc_doc.md",
+    require_starlark_doc_extract = True,
+    stardoc_doc = "//:stardoc_rule_doc",
 )
 
 exports_files(["testdata/fakedeps/dep.bzl"])

test/stardoc_test.bzl

@@ -148,3 +148,37 @@ def _create_test_targets(
         )
     else:
         fail("parameter 'test' must either be 'default' or 'html_tables', but was " + test)
+
+def self_gen_test(
+        name,
+        stardoc_doc,
+        golden_file,
+        require_starlark_doc_extract,
+        **kwargs):
+    """
+    A wrapper around `diff_test_runner.sh` for testing Stardoc's own generated documentation.
+
+    Args:
+      name: A unique name for the test target.
+      stardoc_doc: The Stardoc output being tested.
+      golden_file: Expected Stardoc output.
+      require_starlark_doc_extract: If true, and the native `starlark_doc_extract` rule is not available,
+        then no test target will not be created.
+      **kwargs: Additional arguments for the test.
+    """
+    if require_starlark_doc_extract and not hasattr(native, "starlark_doc_extract"):
+        return
+
+    native.sh_test(
+        name = name,
+        srcs = ["diff_test_runner.sh"],
+        args = [
+            "$(location %s)" % golden_file,
+            "$(location %s)" % stardoc_doc,
+        ],
+        data = [
+            golden_file,
+            stardoc_doc,
+        ],
+        **kwargs
+    )

test/testdata/attribute_defaults_test/golden.md

@@ -21,9 +21,9 @@ This is my rule. It does stuff.
 | <a id="my_rule-a"></a>a |  Some bool   | Boolean | optional |  `False`  |
 | <a id="my_rule-b"></a>b |  Some int   | Integer | optional |  `2`  |
 | <a id="my_rule-c"></a>c |  Some int_list   | List of integers | optional |  `[0, 1]`  |
-| <a id="my_rule-d"></a>d |  Some label   | <a href="https://bazel.build/concepts/labels">Label</a> | optional |  `"//foo:bar"`  |
-| <a id="my_rule-e"></a>e |  Some label_keyed_string_dict   | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | optional |  `{"//foo:bar": "hello", "//bar:baz": "goodbye"}`  |
-| <a id="my_rule-f"></a>f |  Some label_list   | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional |  `["//foo:bar", "//bar:baz"]`  |
+| <a id="my_rule-d"></a>d |  Some label   | <a href="https://bazel.build/concepts/labels">Label</a> | optional |  `"@io_bazel_stardoc//foo:bar"`  |
+| <a id="my_rule-e"></a>e |  Some label_keyed_string_dict   | <a href="https://bazel.build/rules/lib/dict">Dictionary: Label -> String</a> | optional |  `{"@io_bazel_stardoc//foo:bar": "hello", "@io_bazel_stardoc//bar:baz": "goodbye"}`  |
+| <a id="my_rule-f"></a>f |  Some label_list   | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional |  `["@io_bazel_stardoc//foo:bar", "@io_bazel_stardoc//bar:baz"]`  |
 | <a id="my_rule-g"></a>g |  Some string   | String | optional |  `""`  |
 | <a id="my_rule-h"></a>h |  Some string_dict   | <a href="https://bazel.build/rules/lib/dict">Dictionary: String -> String</a> | optional |  `{"animal": "bunny", "color": "orange"}`  |
 | <a id="my_rule-i"></a>i |  Some string_list   | List of strings | optional |  `["cat", "dog"]`  |

test/testdata/misc_apis_test/golden.md

@@ -22,7 +22,7 @@ This rule exercises some of the build API.
 | <a id="my_rule-src"></a>src |  The source file.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional |  `None`  |
 | <a id="my_rule-out"></a>out |  The output file.   | <a href="https://bazel.build/concepts/labels">Label</a> | required |  |
 | <a id="my_rule-extra_arguments"></a>extra_arguments |  -   | List of strings | optional |  `[]`  |
-| <a id="my_rule-tool"></a>tool |  The location of the tool to use.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional |  `"//foo/bar/baz:target"`  |
+| <a id="my_rule-tool"></a>tool |  The location of the tool to use.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional |  `"@io_bazel_stardoc//foo/bar/baz:target"`  |
 
 
 <a id="MyInfo"></a>

test/testdata/module_extension_test/golden.md

@@ -7,7 +7,7 @@ Minimal example of a .bzl file defining a module extension.
 ## my_ext
 
 <pre>
-my_ext = use_extension("//test:testdata/module_extension_test/input.bzl", "my_ext")
+my_ext = use_extension("@io_bazel_stardoc//test:testdata/module_extension_test/input.bzl", "my_ext")
 my_ext.install(<a href="#my_ext.install-artifacts">artifacts</a>)
 my_ext.artifact(<a href="#my_ext.artifact-artifact">artifact</a>, <a href="#my_ext.artifact-group">group</a>)
 </pre>

test/testdata/proto_format_test/golden.binaryproto

@@ -1,21 +1,21 @@
 
-�

+�

 
 my_exampleSmall example of rule.*
 nameA unique name for this target.
 
7
 uselessThis argument will be ignored.2
-"ignoreme""9
+"ignoreme""J
 
-my_example+//test:testdata/proto_format_test/input.bzl�

+my_example<@io_bazel_stardoc//test:testdata/proto_format_test/input.bzl�

 example$Stores information about an example. 
 fooA string representing foo 
 barA string representing bar 
-bazA string representing baz"6
-example+//test:testdata/proto_format_test/input.bzl�
+bazA string representing baz"G
+example<@io_bazel_stardoc//test:testdata/proto_format_test/input.bzl�
 check_function%
 fooA unique name for this rule. 
�
Runs some checks on the given function parameter.
 
 This rule runs checks on a given function parameter.
 Use `bazel build` to run the check.
-2=
-check_function+//test:testdata/proto_format_test/input.bzl* Input file for proto format test2+//test:testdata/proto_format_test/input.bzl
+2N
+check_function<@io_bazel_stardoc//test:testdata/proto_format_test/input.bzl* Input file for proto format test2<@io_bazel_stardoc//test:testdata/proto_format_test/input.bzl