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.
diff --git a/docs/stardoc_rule.md b/docs/stardoc_rule.md
index 0d8f0a8..18bb219 100644
--- a/docs/stardoc_rule.md
+++ b/docs/stardoc_rule.md
@@ -9,7 +9,8 @@
<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 @@
| <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 |
diff --git a/stardoc/stardoc.bzl b/stardoc/stardoc.bzl
index 09e51b1..6a3fbe7 100644
--- a/stardoc/stardoc.bzl
+++ b/stardoc/stardoc.bzl
@@ -37,6 +37,7 @@
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 @@
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 @@
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)
)
diff --git a/test/BUILD b/test/BUILD
index 141868f..be7077f 100644
--- a/test/BUILD
+++ b/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"])
diff --git a/test/stardoc_test.bzl b/test/stardoc_test.bzl
index f4fc9a9..d782643 100644
--- a/test/stardoc_test.bzl
+++ b/test/stardoc_test.bzl
@@ -148,3 +148,37 @@
)
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
+ )
diff --git a/test/testdata/attribute_defaults_test/golden.md b/test/testdata/attribute_defaults_test/golden.md
index 221d32d..64adeab 100644
--- a/test/testdata/attribute_defaults_test/golden.md
+++ b/test/testdata/attribute_defaults_test/golden.md
@@ -21,9 +21,9 @@
| <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"]` |
diff --git a/test/testdata/misc_apis_test/golden.md b/test/testdata/misc_apis_test/golden.md
index 1512fd0..3e3ef3c 100644
--- a/test/testdata/misc_apis_test/golden.md
+++ b/test/testdata/misc_apis_test/golden.md
@@ -22,7 +22,7 @@
| <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>
diff --git a/test/testdata/module_extension_test/golden.md b/test/testdata/module_extension_test/golden.md
index 3b8c51e..addfc77 100644
--- a/test/testdata/module_extension_test/golden.md
+++ b/test/testdata/module_extension_test/golden.md
@@ -7,7 +7,7 @@
## 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>
diff --git a/test/testdata/proto_format_test/golden.binaryproto b/test/testdata/proto_format_test/golden.binaryproto
index 5685b48..ff1d54b 100644
--- a/test/testdata/proto_format_test/golden.binaryproto
+++ b/test/testdata/proto_format_test/golden.binaryproto
@@ -1,21 +1,21 @@
-Ä
+Õ
my_exampleSmall example of rule.*
name A unique name for this target. 7
useless This 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%
foo A 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
\ No newline at end of file
+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
\ No newline at end of file
