Change some core semantics of skydoc.
- Change Skydoc to only document exported symbols in the target file, instead of all exported symbols in the transitive dependencies of the target file. This circumvents a prior error scenario where main.bzl could depend on dep.bzl, and both export a rule named ?my_rule?, which would result in a conflict.
- Offer the option to specify whitelisted symbols for which to output documentation, allowing a user to only request documentation for a subset of rules defined in a given file. This allows more granular control of documentation layout.
RELNOTES: None.
PiperOrigin-RevId: 204161197
diff --git a/src/test/java/com/google/devtools/build/skydoc/BUILD b/src/test/java/com/google/devtools/build/skydoc/BUILD
index 31b365d..f36e9db 100644
--- a/src/test/java/com/google/devtools/build/skydoc/BUILD
+++ b/src/test/java/com/google/devtools/build/skydoc/BUILD
@@ -105,3 +105,17 @@
input_file = "testdata/attribute_types_test/input.bzl",
skydoc = "//src/main/java/com/google/devtools/build/skydoc",
)
+
+skydoc_test(
+ name = "filter_rules_test",
+ golden_file = "testdata/filter_rules_test/golden.txt",
+ input_file = "testdata/filter_rules_test/input.bzl",
+ skydoc = "//src/main/java/com/google/devtools/build/skydoc",
+ whitelisted_symbols = [
+ "my_rule",
+ "whitelisted_dep_rule",
+ ],
+ deps = [
+ "testdata/filter_rules_test/dep.bzl",
+ ],
+)
diff --git a/src/test/java/com/google/devtools/build/skydoc/SkydocTest.java b/src/test/java/com/google/devtools/build/skydoc/SkydocTest.java
index 5bf7a95..185547d 100644
--- a/src/test/java/com/google/devtools/build/skydoc/SkydocTest.java
+++ b/src/test/java/com/google/devtools/build/skydoc/SkydocTest.java
@@ -168,7 +168,10 @@
"load('//lib:rule_impl.bzl', 'rule_impl')",
"load(':docstring.bzl', 'doc_string')",
"",
- "some_var = 1",
+ "_hidden_rule = rule(",
+ " doc = doc_string,",
+ " implementation = rule_impl,",
+ ")",
"",
"dep_rule = rule(",
" doc = doc_string,",
@@ -178,7 +181,7 @@
scratch.file(
"/test/main.bzl",
"load('//lib:rule_impl.bzl', 'rule_impl')",
- "load('//deps/foo:dep_rule.bzl', 'some_var')",
+ "load('//deps/foo:dep_rule.bzl', 'dep_rule')",
"",
"main_rule = rule(",
" doc = 'Main rule',",
@@ -194,6 +197,8 @@
Map<String, RuleInfo> ruleInfoMap = ruleInfoMapBuilder.build();
+ // dep_rule is available here, even though it was not defined in main.bzl, because it is
+ // imported in main.bzl. Thus, it's a top-level symbol in main.bzl.
assertThat(ruleInfoMap.keySet()).containsExactly("main_rule", "dep_rule");
assertThat(ruleInfoMap.get("main_rule").getDocString()).isEqualTo("Main rule");
assertThat(ruleInfoMap.get("dep_rule").getDocString()).isEqualTo("Dep rule");
diff --git a/src/test/java/com/google/devtools/build/skydoc/skydoc_e2e_test_runner.sh b/src/test/java/com/google/devtools/build/skydoc/skydoc_e2e_test_runner.sh
index 8a9a1c7..ac40e9a 100755
--- a/src/test/java/com/google/devtools/build/skydoc/skydoc_e2e_test_runner.sh
+++ b/src/test/java/com/google/devtools/build/skydoc/skydoc_e2e_test_runner.sh
@@ -19,13 +19,16 @@
set -u
skydoc_bin=$1
-input_file=$2
-golden_file=$3
+shift 1
+input_file=$1
+shift 1
+golden_file=$1
+shift 1
actual_file="${TEST_TMPDIR}/actual"
set -e
-${skydoc_bin} ${input_file} ${actual_file}
+${skydoc_bin} ${input_file} ${actual_file} $@
set +e
DIFF="$(diff ${actual_file} ${golden_file})"
diff --git a/src/test/java/com/google/devtools/build/skydoc/skydoc_test.bzl b/src/test/java/com/google/devtools/build/skydoc/skydoc_test.bzl
index c63ceda..455b45d 100644
--- a/src/test/java/com/google/devtools/build/skydoc/skydoc_test.bzl
+++ b/src/test/java/com/google/devtools/build/skydoc/skydoc_test.bzl
@@ -20,7 +20,7 @@
# the golden file if changes are made to skydoc.
"""Convenience macro for skydoc tests."""
-def skydoc_test(name, input_file, golden_file, skydoc, deps = []):
+def skydoc_test(name, input_file, golden_file, skydoc, deps = [], whitelisted_symbols = []):
"""Creates a test target and golden-file regeneration target for skydoc testing.
The test target is named "{name}_e2e_test".
@@ -34,6 +34,9 @@
is run on the input file.
skydoc: The label string of the skydoc binary.
deps: A list of label strings of skylark file dependencies of the input_file.
+ whitelisted_symbols: A list of strings representing top-level symbols in the input file
+ to generate documentation for. If empty, documentation for all top-level symbols
+ will be generated.
"""
output_golden_file = "%s_output.txt" % name
native.sh_test(
@@ -43,7 +46,7 @@
"$(location %s)" % skydoc,
"$(location %s)" % input_file,
"$(location %s)" % golden_file,
- ],
+ ] + whitelisted_symbols,
data = [
input_file,
golden_file,
@@ -58,6 +61,7 @@
] + deps,
outs = [output_golden_file],
cmd = "$(location %s) " % skydoc +
- "$(location %s) $(location %s)" % (input_file, output_golden_file),
+ "$(location %s) $(location %s) " % (input_file, output_golden_file) +
+ " ".join(whitelisted_symbols),
tools = [skydoc],
)
diff --git a/src/test/java/com/google/devtools/build/skydoc/testdata/filter_rules_test/dep.bzl b/src/test/java/com/google/devtools/build/skydoc/testdata/filter_rules_test/dep.bzl
new file mode 100644
index 0000000..8213e0d
--- /dev/null
+++ b/src/test/java/com/google/devtools/build/skydoc/testdata/filter_rules_test/dep.bzl
@@ -0,0 +1,12 @@
+def my_rule_impl(ctx):
+ return struct()
+
+my_rule = rule(
+ implementation = my_rule_impl,
+ doc = "This is the dep rule. It does stuff.",
+ attrs = {
+ "first": attr.label(mandatory = True, doc = "dep's my_rule doc string",
+ allow_files = True, single_file = True),
+ "second": attr.string_dict(mandatory = True),
+ },
+)
diff --git a/src/test/java/com/google/devtools/build/skydoc/testdata/filter_rules_test/golden.txt b/src/test/java/com/google/devtools/build/skydoc/testdata/filter_rules_test/golden.txt
new file mode 100644
index 0000000..457c1b7
--- /dev/null
+++ b/src/test/java/com/google/devtools/build/skydoc/testdata/filter_rules_test/golden.txt
@@ -0,0 +1,90 @@
+<a name="#my_rule"></a>
+## my_rule
+
+<pre>
+my_rule(name, first, second)
+</pre>
+
+This is my rule. It does stuff.
+
+### Attributes
+
+<table class="params-table">
+ <colgroup>
+ <col class="col-param" />
+ <col class="col-description" />
+ </colgroup>
+ <tbody>
+ <tr id="#my_rule_name">
+ <td><code>name</code></td>
+ <td>
+ String; required
+ <p>
+ A unique name for this rule.
+ </p>
+ </td>
+ </tr>
+ <tr id="#my_rule_first">
+ <td><code>first</code></td>
+ <td>
+ Label; required
+ <p>
+ first my_rule doc string
+ </p>
+ </td>
+ </tr>
+ <tr id="#my_rule_second">
+ <td><code>second</code></td>
+ <td>
+ Dictionary: String -> String; required
+ </td>
+ </tr>
+ </tbody>
+</table>
+
+
+<a name="#whitelisted_dep_rule"></a>
+## whitelisted_dep_rule
+
+<pre>
+whitelisted_dep_rule(name, first, second)
+</pre>
+
+This is the dep rule. It does stuff.
+
+### Attributes
+
+<table class="params-table">
+ <colgroup>
+ <col class="col-param" />
+ <col class="col-description" />
+ </colgroup>
+ <tbody>
+ <tr id="#whitelisted_dep_rule_name">
+ <td><code>name</code></td>
+ <td>
+ String; required
+ <p>
+ A unique name for this rule.
+ </p>
+ </td>
+ </tr>
+ <tr id="#whitelisted_dep_rule_first">
+ <td><code>first</code></td>
+ <td>
+ Label; required
+ <p>
+ dep's my_rule doc string
+ </p>
+ </td>
+ </tr>
+ <tr id="#whitelisted_dep_rule_second">
+ <td><code>second</code></td>
+ <td>
+ Dictionary: String -> String; required
+ </td>
+ </tr>
+ </tbody>
+</table>
+
+
diff --git a/src/test/java/com/google/devtools/build/skydoc/testdata/filter_rules_test/input.bzl b/src/test/java/com/google/devtools/build/skydoc/testdata/filter_rules_test/input.bzl
new file mode 100644
index 0000000..3ec3530
--- /dev/null
+++ b/src/test/java/com/google/devtools/build/skydoc/testdata/filter_rules_test/input.bzl
@@ -0,0 +1,34 @@
+load(":dep.bzl",
+ "my_rule_impl",
+ dep_rule = "my_rule")
+
+def my_rule_impl(ctx):
+ return struct()
+
+my_rule = rule(
+ implementation = my_rule_impl,
+ doc = "This is my rule. It does stuff.",
+ attrs = {
+ "first": attr.label(mandatory = True, doc = "first my_rule doc string",
+ allow_files = True, single_file = True),
+ "second": attr.string_dict(mandatory = True),
+ },
+)
+
+other_rule = rule(
+ implementation = my_rule_impl,
+ doc = "This is another rule.",
+ attrs = {
+ "test": attr.string_dict(mandatory = True),
+ },
+)
+
+whitelisted_dep_rule = dep_rule
+
+yet_another_rule = rule(
+ implementation = my_rule_impl,
+ doc = "This is yet another rule",
+ attrs = {
+ "test": attr.string_dict(mandatory = True),
+ },
+)
