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

13 files changed, 421 insertions, 32 deletions

diff --git a/src/test/java/com/google/devtools/build/skydoc/BUILD b/src/test/java/com/google/devtools/build/skydoc/BUILD
index d235bf8834..c12329f597 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(
 )
 
 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 870fa67e52..a1d7acbe29 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 @@ public final class SkydocTest extends SkylarkTestCase {
     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 c7ed05dd3d..e7c4c5f090 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 36642e45dc..882f540741 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 45699d1a71..9674b82f4d 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 274e1f2744..7ab9fc0247 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 5880c8c67c..0619f29bcb 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 b1a4a66325..1b2d0a0b52 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 b331e602c2..efd5ed460c 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 @@ my_rule = rule(
     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 @@ other_rule = rule(
     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 b1a4a66325..7d37f798f3 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 50b71f076b..d86c0c70d5 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 de1548b420..08550fe4af 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 @@ my_rule = rule(
     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 ab79bcf5d6..44040ee908 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>
+