From 93adb10c639fe3b7e5bfb17802b13ea46379e56e Mon Sep 17 00:00:00 2001 From: cparsons Date: Wed, 11 Jul 2018 11:44:17 -0700 Subject: 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 --- .../java/com/google/devtools/build/skydoc/BUILD | 14 ++++ .../google/devtools/build/skydoc/SkydocTest.java | 9 ++- .../build/skydoc/skydoc_e2e_test_runner.sh | 9 ++- .../google/devtools/build/skydoc/skydoc_test.bzl | 10 ++- .../skydoc/testdata/filter_rules_test/dep.bzl | 12 +++ .../skydoc/testdata/filter_rules_test/golden.txt | 90 ++++++++++++++++++++++ .../skydoc/testdata/filter_rules_test/input.bzl | 34 ++++++++ 7 files changed, 170 insertions(+), 8 deletions(-) create mode 100644 src/test/java/com/google/devtools/build/skydoc/testdata/filter_rules_test/dep.bzl create mode 100644 src/test/java/com/google/devtools/build/skydoc/testdata/filter_rules_test/golden.txt create mode 100644 src/test/java/com/google/devtools/build/skydoc/testdata/filter_rules_test/input.bzl (limited to 'src/test/java/com/google/devtools/build') diff --git a/src/test/java/com/google/devtools/build/skydoc/BUILD b/src/test/java/com/google/devtools/build/skydoc/BUILD index 31b365d394..f36e9dbdc8 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 @@ skydoc_test( 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 5bf7a95704..185547d580 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 @@ public final class SkydocTest extends SkylarkTestCase { "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 @@ public final class SkydocTest extends SkylarkTestCase { 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 @@ public final class SkydocTest extends SkylarkTestCase { Map 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 8a9a1c7010..ac40e9abde 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 c63cedaa08..455b45d859 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 @@ def skydoc_test(name, input_file, golden_file, skydoc, deps = []): 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 @@ def skydoc_test(name, input_file, golden_file, skydoc, deps = []): "$(location %s)" % skydoc, "$(location %s)" % input_file, "$(location %s)" % golden_file, - ], + ] + whitelisted_symbols, data = [ input_file, golden_file, @@ -58,6 +61,7 @@ def skydoc_test(name, input_file, golden_file, skydoc, deps = []): ] + 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 0000000000..8213e0d794 --- /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 0000000000..457c1b7ef9 --- /dev/null +++ b/src/test/java/com/google/devtools/build/skydoc/testdata/filter_rules_test/golden.txt @@ -0,0 +1,90 @@ + +## my_rule + +
+my_rule(name, first, second)
+
+ +This is my rule. It does stuff. + +### Attributes + + + + + + + + + + + + + + + + + + + + +
name + String; required +

+ A unique name for this rule. +

+
first + Label; required +

+ first my_rule doc string +

+
second + Dictionary: String -> String; required +
+ + + +## whitelisted_dep_rule + +
+whitelisted_dep_rule(name, first, second)
+
+ +This is the dep rule. It does stuff. + +### Attributes + + + + + + + + + + + + + + + + + + + + +
name + String; required +

+ A unique name for this rule. +

+
first + Label; required +

+ dep's my_rule doc string +

+
second + Dictionary: String -> String; required +
+ + 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 0000000000..3ec3530279 --- /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), + }, +) -- cgit v1.2.3