Simple Markdown rendering for skydoc
This uses apache velocity engine templates to create markdown-HTML. There are other alternatives, but there is already precedent for depending on this library from docgen.
RELNOTES: None.
PiperOrigin-RevId: 203795431
diff --git a/src/test/java/com/google/devtools/build/skydoc/BUILD b/src/test/java/com/google/devtools/build/skydoc/BUILD
index d235bf8..c12329f 100644
--- a/src/test/java/com/google/devtools/build/skydoc/BUILD
+++ b/src/test/java/com/google/devtools/build/skydoc/BUILD
@@ -67,6 +67,13 @@
)
skydoc_test(
+ name = "cpp_basic_test",
+ golden_file = "testdata/cpp_basic_test/golden.txt",
+ input_file = "testdata/cpp_basic_test/input.bzl",
+ skydoc = "//src/main/java/com/google/devtools/build/skydoc",
+)
+
+skydoc_test(
name = "java_basic_test",
golden_file = "testdata/java_basic_test/golden.txt",
input_file = "testdata/java_basic_test/input.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 870fa67..a1d7acb 100644
--- a/src/test/java/com/google/devtools/build/skydoc/SkydocTest.java
+++ b/src/test/java/com/google/devtools/build/skydoc/SkydocTest.java
@@ -97,11 +97,16 @@
Entry<String, RuleInfo> ruleInfo = Iterables.getOnlyElement(ruleInfos.entrySet());
assertThat(ruleInfo.getKey()).isEqualTo("my_rule");
assertThat(ruleInfo.getValue().getDocString()).isEqualTo("This is my rule. It does stuff.");
- assertThat(ruleInfo.getValue().getAttrNames()).containsExactly(
- "first", "second", "third", "fourth");
+ assertThat(getAttrNames(ruleInfo.getValue())).containsExactly(
+ "first", "fourth", "second", "third").inOrder();
assertThat(unexportedRuleInfos.build()).isEmpty();
}
+ private static Iterable<String> getAttrNames(RuleInfo ruleInfo) {
+ return ruleInfo.getAttributes().stream().map(attr -> attr.getName())
+ .collect(Collectors.toList());
+ }
+
@Test
public void testMultipleRuleNames() throws Exception {
scratch.file(
diff --git a/src/test/java/com/google/devtools/build/skydoc/testdata/android_basic_test/golden.txt b/src/test/java/com/google/devtools/build/skydoc/testdata/android_basic_test/golden.txt
index c7ed05d..e7c4c5f 100644
--- a/src/test/java/com/google/devtools/build/skydoc/testdata/android_basic_test/golden.txt
+++ b/src/test/java/com/google/devtools/build/skydoc/testdata/android_basic_test/golden.txt
@@ -1,4 +1,37 @@
-android_related_rule
+<a name="#android_related_rule"></a>
+## android_related_rule
+
+<pre>
+android_related_rule(first, fourth, second, third)
+</pre>
+
This rule does android-related things.
-first,second,third,fourth
+
+### Attributes
+
+<table class="params-table">
+ <colgroup>
+ <col class="col-param" />
+ <col class="col-description" />
+ </colgroup>
+ <tbody>
+ <tr id="#android_related_rule_first">
+ <td><code>first</code></td>
+ <td></td>
+ </tr>
+ <tr id="#android_related_rule_fourth">
+ <td><code>fourth</code></td>
+ <td></td>
+ </tr>
+ <tr id="#android_related_rule_second">
+ <td><code>second</code></td>
+ <td></td>
+ </tr>
+ <tr id="#android_related_rule_third">
+ <td><code>third</code></td>
+ <td></td>
+ </tr>
+ </tbody>
+</table>
+
diff --git a/src/test/java/com/google/devtools/build/skydoc/testdata/apple_basic_test/golden.txt b/src/test/java/com/google/devtools/build/skydoc/testdata/apple_basic_test/golden.txt
index 36642e4..882f540 100644
--- a/src/test/java/com/google/devtools/build/skydoc/testdata/apple_basic_test/golden.txt
+++ b/src/test/java/com/google/devtools/build/skydoc/testdata/apple_basic_test/golden.txt
@@ -1,4 +1,37 @@
-apple_related_rule
+<a name="#apple_related_rule"></a>
+## apple_related_rule
+
+<pre>
+apple_related_rule(first, fourth, second, third)
+</pre>
+
This rule does apple-related things.
-first,second,third,fourth
+
+### Attributes
+
+<table class="params-table">
+ <colgroup>
+ <col class="col-param" />
+ <col class="col-description" />
+ </colgroup>
+ <tbody>
+ <tr id="#apple_related_rule_first">
+ <td><code>first</code></td>
+ <td></td>
+ </tr>
+ <tr id="#apple_related_rule_fourth">
+ <td><code>fourth</code></td>
+ <td></td>
+ </tr>
+ <tr id="#apple_related_rule_second">
+ <td><code>second</code></td>
+ <td></td>
+ </tr>
+ <tr id="#apple_related_rule_third">
+ <td><code>third</code></td>
+ <td></td>
+ </tr>
+ </tbody>
+</table>
+
diff --git a/src/test/java/com/google/devtools/build/skydoc/testdata/cpp_basic_test/golden.txt b/src/test/java/com/google/devtools/build/skydoc/testdata/cpp_basic_test/golden.txt
index 45699d1..9674b82 100644
--- a/src/test/java/com/google/devtools/build/skydoc/testdata/cpp_basic_test/golden.txt
+++ b/src/test/java/com/google/devtools/build/skydoc/testdata/cpp_basic_test/golden.txt
@@ -1,4 +1,37 @@
-cpp_related_rule
+<a name="#cpp_related_rule"></a>
+## cpp_related_rule
+
+<pre>
+cpp_related_rule(first, fourth, second, third)
+</pre>
+
This rule does cpp-related things.
-first,second,third,fourth
+
+### Attributes
+
+<table class="params-table">
+ <colgroup>
+ <col class="col-param" />
+ <col class="col-description" />
+ </colgroup>
+ <tbody>
+ <tr id="#cpp_related_rule_first">
+ <td><code>first</code></td>
+ <td></td>
+ </tr>
+ <tr id="#cpp_related_rule_fourth">
+ <td><code>fourth</code></td>
+ <td></td>
+ </tr>
+ <tr id="#cpp_related_rule_second">
+ <td><code>second</code></td>
+ <td></td>
+ </tr>
+ <tr id="#cpp_related_rule_third">
+ <td><code>third</code></td>
+ <td></td>
+ </tr>
+ </tbody>
+</table>
+
diff --git a/src/test/java/com/google/devtools/build/skydoc/testdata/java_basic_test/golden.txt b/src/test/java/com/google/devtools/build/skydoc/testdata/java_basic_test/golden.txt
index 274e1f2..7ab9fc0 100644
--- a/src/test/java/com/google/devtools/build/skydoc/testdata/java_basic_test/golden.txt
+++ b/src/test/java/com/google/devtools/build/skydoc/testdata/java_basic_test/golden.txt
@@ -1,4 +1,37 @@
-java_related_rule
+<a name="#java_related_rule"></a>
+## java_related_rule
+
+<pre>
+java_related_rule(first, fourth, second, third)
+</pre>
+
This rule does java-related things.
-first,second,third,fourth
+
+### Attributes
+
+<table class="params-table">
+ <colgroup>
+ <col class="col-param" />
+ <col class="col-description" />
+ </colgroup>
+ <tbody>
+ <tr id="#java_related_rule_first">
+ <td><code>first</code></td>
+ <td></td>
+ </tr>
+ <tr id="#java_related_rule_fourth">
+ <td><code>fourth</code></td>
+ <td></td>
+ </tr>
+ <tr id="#java_related_rule_second">
+ <td><code>second</code></td>
+ <td></td>
+ </tr>
+ <tr id="#java_related_rule_third">
+ <td><code>third</code></td>
+ <td></td>
+ </tr>
+ </tbody>
+</table>
+
diff --git a/src/test/java/com/google/devtools/build/skydoc/testdata/misc_apis_test/golden.txt b/src/test/java/com/google/devtools/build/skydoc/testdata/misc_apis_test/golden.txt
index 5880c8c..0619f29 100644
--- a/src/test/java/com/google/devtools/build/skydoc/testdata/misc_apis_test/golden.txt
+++ b/src/test/java/com/google/devtools/build/skydoc/testdata/misc_apis_test/golden.txt
@@ -1,4 +1,37 @@
-my_rule
+<a name="#my_rule"></a>
+## my_rule
+
+<pre>
+my_rule(first, fourth, second, third)
+</pre>
+
This rule exercises some of the build API.
-first,second,third,fourth
+
+### Attributes
+
+<table class="params-table">
+ <colgroup>
+ <col class="col-param" />
+ <col class="col-description" />
+ </colgroup>
+ <tbody>
+ <tr id="#my_rule_first">
+ <td><code>first</code></td>
+ <td></td>
+ </tr>
+ <tr id="#my_rule_fourth">
+ <td><code>fourth</code></td>
+ <td></td>
+ </tr>
+ <tr id="#my_rule_second">
+ <td><code>second</code></td>
+ <td></td>
+ </tr>
+ <tr id="#my_rule_third">
+ <td><code>third</code></td>
+ <td></td>
+ </tr>
+ </tbody>
+</table>
+
diff --git a/src/test/java/com/google/devtools/build/skydoc/testdata/multiple_files_test/golden.txt b/src/test/java/com/google/devtools/build/skydoc/testdata/multiple_files_test/golden.txt
index b1a4a66..1b2d0a0 100644
--- a/src/test/java/com/google/devtools/build/skydoc/testdata/multiple_files_test/golden.txt
+++ b/src/test/java/com/google/devtools/build/skydoc/testdata/multiple_files_test/golden.txt
@@ -1,12 +1,83 @@
-my_rule
+<a name="#my_rule"></a>
+## my_rule
+
+<pre>
+my_rule(first, second)
+</pre>
+
This is my rule. It does stuff.
-first,second
-other_rule
+### Attributes
+
+<table class="params-table">
+ <colgroup>
+ <col class="col-param" />
+ <col class="col-description" />
+ </colgroup>
+ <tbody>
+ <tr id="#my_rule_first">
+ <td><code>first</code></td>
+ <td>first my_rule doc string</td>
+ </tr>
+ <tr id="#my_rule_second">
+ <td><code>second</code></td>
+ <td></td>
+ </tr>
+ </tbody>
+</table>
+
+
+<a name="#other_rule"></a>
+## other_rule
+
+<pre>
+other_rule(fourth, third)
+</pre>
+
This is another rule.
-third,fourth
-yet_another_rule
+### Attributes
+
+<table class="params-table">
+ <colgroup>
+ <col class="col-param" />
+ <col class="col-description" />
+ </colgroup>
+ <tbody>
+ <tr id="#other_rule_fourth">
+ <td><code>fourth</code></td>
+ <td></td>
+ </tr>
+ <tr id="#other_rule_third">
+ <td><code>third</code></td>
+ <td>third other_rule doc string</td>
+ </tr>
+ </tbody>
+</table>
+
+
+<a name="#yet_another_rule"></a>
+## yet_another_rule
+
+<pre>
+yet_another_rule(fifth)
+</pre>
+
This is yet another rule
-fifth
+
+### Attributes
+
+<table class="params-table">
+ <colgroup>
+ <col class="col-param" />
+ <col class="col-description" />
+ </colgroup>
+ <tbody>
+ <tr id="#yet_another_rule_fifth">
+ <td><code>fifth</code></td>
+ <td></td>
+ </tr>
+ </tbody>
+</table>
+
diff --git a/src/test/java/com/google/devtools/build/skydoc/testdata/multiple_files_test/input.bzl b/src/test/java/com/google/devtools/build/skydoc/testdata/multiple_files_test/input.bzl
index b331e60..efd5ed4 100644
--- a/src/test/java/com/google/devtools/build/skydoc/testdata/multiple_files_test/input.bzl
+++ b/src/test/java/com/google/devtools/build/skydoc/testdata/multiple_files_test/input.bzl
@@ -4,7 +4,8 @@
implementation = my_rule_impl,
doc = "This is my rule. It does stuff.",
attrs = {
- "first": attr.label(mandatory = True, allow_files = True, single_file = True),
+ "first": attr.label(mandatory = True, doc = "first my_rule doc string",
+ allow_files = True, single_file = True),
"second": attr.string_dict(mandatory = True),
},
)
@@ -13,7 +14,8 @@
implementation = my_rule_impl,
doc = "This is another rule.",
attrs = {
- "third": attr.label(mandatory = True, allow_files = True, single_file = True),
+ "third": attr.label(mandatory = True, doc = "third other_rule doc string",
+ allow_files = True, single_file = True),
"fourth": attr.string_dict(mandatory = True),
},
)
diff --git a/src/test/java/com/google/devtools/build/skydoc/testdata/multiple_rules_test/golden.txt b/src/test/java/com/google/devtools/build/skydoc/testdata/multiple_rules_test/golden.txt
index b1a4a66..7d37f79 100644
--- a/src/test/java/com/google/devtools/build/skydoc/testdata/multiple_rules_test/golden.txt
+++ b/src/test/java/com/google/devtools/build/skydoc/testdata/multiple_rules_test/golden.txt
@@ -1,12 +1,83 @@
-my_rule
+<a name="#my_rule"></a>
+## my_rule
+
+<pre>
+my_rule(first, second)
+</pre>
+
This is my rule. It does stuff.
-first,second
-other_rule
+### Attributes
+
+<table class="params-table">
+ <colgroup>
+ <col class="col-param" />
+ <col class="col-description" />
+ </colgroup>
+ <tbody>
+ <tr id="#my_rule_first">
+ <td><code>first</code></td>
+ <td></td>
+ </tr>
+ <tr id="#my_rule_second">
+ <td><code>second</code></td>
+ <td></td>
+ </tr>
+ </tbody>
+</table>
+
+
+<a name="#other_rule"></a>
+## other_rule
+
+<pre>
+other_rule(fourth, third)
+</pre>
+
This is another rule.
-third,fourth
-yet_another_rule
+### Attributes
+
+<table class="params-table">
+ <colgroup>
+ <col class="col-param" />
+ <col class="col-description" />
+ </colgroup>
+ <tbody>
+ <tr id="#other_rule_fourth">
+ <td><code>fourth</code></td>
+ <td></td>
+ </tr>
+ <tr id="#other_rule_third">
+ <td><code>third</code></td>
+ <td></td>
+ </tr>
+ </tbody>
+</table>
+
+
+<a name="#yet_another_rule"></a>
+## yet_another_rule
+
+<pre>
+yet_another_rule(fifth)
+</pre>
+
This is yet another rule
-fifth
+
+### Attributes
+
+<table class="params-table">
+ <colgroup>
+ <col class="col-param" />
+ <col class="col-description" />
+ </colgroup>
+ <tbody>
+ <tr id="#yet_another_rule_fifth">
+ <td><code>fifth</code></td>
+ <td></td>
+ </tr>
+ </tbody>
+</table>
+
diff --git a/src/test/java/com/google/devtools/build/skydoc/testdata/simple_test/golden.txt b/src/test/java/com/google/devtools/build/skydoc/testdata/simple_test/golden.txt
index 50b71f0..d86c0c7 100644
--- a/src/test/java/com/google/devtools/build/skydoc/testdata/simple_test/golden.txt
+++ b/src/test/java/com/google/devtools/build/skydoc/testdata/simple_test/golden.txt
@@ -1,4 +1,37 @@
-my_rule
+<a name="#my_rule"></a>
+## my_rule
+
+<pre>
+my_rule(first, fourth, second, third)
+</pre>
+
This is my rule. It does stuff.
-first,second,third,fourth
+
+### Attributes
+
+<table class="params-table">
+ <colgroup>
+ <col class="col-param" />
+ <col class="col-description" />
+ </colgroup>
+ <tbody>
+ <tr id="#my_rule_first">
+ <td><code>first</code></td>
+ <td>first doc string</td>
+ </tr>
+ <tr id="#my_rule_fourth">
+ <td><code>fourth</code></td>
+ <td>fourth doc string</td>
+ </tr>
+ <tr id="#my_rule_second">
+ <td><code>second</code></td>
+ <td></td>
+ </tr>
+ <tr id="#my_rule_third">
+ <td><code>third</code></td>
+ <td></td>
+ </tr>
+ </tbody>
+</table>
+
diff --git a/src/test/java/com/google/devtools/build/skydoc/testdata/simple_test/input.bzl b/src/test/java/com/google/devtools/build/skydoc/testdata/simple_test/input.bzl
index de1548b..08550fe 100644
--- a/src/test/java/com/google/devtools/build/skydoc/testdata/simple_test/input.bzl
+++ b/src/test/java/com/google/devtools/build/skydoc/testdata/simple_test/input.bzl
@@ -5,9 +5,10 @@
implementation = my_rule_impl,
doc = "This is my rule. It does stuff.",
attrs = {
- "first": attr.label(mandatory = True, allow_files = True, single_file = True),
+ "first": attr.label(mandatory = True, doc = "first doc string",
+ allow_files = True, single_file = True),
"second": attr.string_dict(mandatory = True),
"third": attr.output(mandatory = True),
- "fourth": attr.bool(default = False, mandatory = False),
+ "fourth": attr.bool(default = False, doc = "fourth doc string", mandatory = False),
},
)
diff --git a/src/test/java/com/google/devtools/build/skydoc/testdata/unknown_name_test/golden.txt b/src/test/java/com/google/devtools/build/skydoc/testdata/unknown_name_test/golden.txt
index ab79bcf..44040ee 100644
--- a/src/test/java/com/google/devtools/build/skydoc/testdata/unknown_name_test/golden.txt
+++ b/src/test/java/com/google/devtools/build/skydoc/testdata/unknown_name_test/golden.txt
@@ -1,3 +1,37 @@
-<unknown name>
-first,second,third,fourth
+<a name="#<unknown name>"></a>
+## <unknown name>
+
+<pre>
+<unknown name>(first, fourth, second, third)
+</pre>
+
+
+
+### Attributes
+
+<table class="params-table">
+ <colgroup>
+ <col class="col-param" />
+ <col class="col-description" />
+ </colgroup>
+ <tbody>
+ <tr id="#<unknown name>_first">
+ <td><code>first</code></td>
+ <td></td>
+ </tr>
+ <tr id="#<unknown name>_fourth">
+ <td><code>fourth</code></td>
+ <td></td>
+ </tr>
+ <tr id="#<unknown name>_second">
+ <td><code>second</code></td>
+ <td></td>
+ </tr>
+ <tr id="#<unknown name>_third">
+ <td><code>third</code></td>
+ <td></td>
+ </tr>
+ </tbody>
+</table>
+
