Accept input templates into Stardoc rule

This allows user to specify their own custom velocity-engine templates, effectively customizing their output.

Full documentation pending in a future change.

7 files changed, 173 insertions, 4 deletions

diff --git a/stardoc/BUILD b/stardoc/BUILD
index 401517d..c49a67e 100644
--- a/stardoc/BUILD
+++ b/stardoc/BUILD
@@ -2,6 +2,13 @@ licenses(["notice"])  # Apache 2.0
 
 package(default_visibility = ["//visibility:public"])
 
+exports_files([
+    "templates/header.vm",
+    "templates/func.vm",
+    "templates/provider.vm",
+    "templates/rule.vm",
+])
+
 load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 load("//stardoc:stardoc.bzl", "stardoc")
 load("@rules_java//java:defs.bzl", "java_binary", "java_import")
diff --git a/stardoc/stardoc.bzl b/stardoc/stardoc.bzl
index 0059358..c511d22 100644
--- a/stardoc/stardoc.bzl
+++ b/stardoc/stardoc.bzl
@@ -56,7 +56,7 @@ def _stardoc_impl(ctx):
     )
     stardoc_args.add_all(ctx.attr.semantic_flags)
     stardoc = ctx.executable.stardoc
-    
+
     if ctx.attr.format == "proto":
         stardoc_args.add("--output=" + out_file.path)
         ctx.actions.run(
@@ -83,17 +83,21 @@ def _stardoc_impl(ctx):
         renderer_args = ctx.actions.args()
         renderer_args.add("--input=" + str(proto_file.path))
         renderer_args.add("--output=" + str(ctx.outputs.out.path))
+        renderer_args.add("--header_template=" + str(ctx.file.header_template.path))
+        renderer_args.add("--func_template=" + str(ctx.file.func_template.path))
+        renderer_args.add("--provider_template=" + str(ctx.file.provider_template.path))
+        renderer_args.add("--rule_template=" + str(ctx.file.rule_template.path))
         renderer = ctx.executable.renderer
         ctx.actions.run(
             outputs = [out_file],
-            inputs = [proto_file],
+            inputs = [proto_file, ctx.file.header_template, ctx.file.func_template, ctx.file.provider_template, ctx.file.rule_template],
             executable = renderer,
             arguments = [renderer_args],
             mnemonic = "Renderer",
             progress_message = ("Converting proto format of %s to markdown format" %
                                 (ctx.label.name)),
         )
-        
+
 stardoc = rule(
     _stardoc_impl,
     doc = """
@@ -152,5 +156,25 @@ non-default semantic flags required to use the given Starlark symbols.
             cfg = "host",
             executable = True,
         ),
+        "header_template": attr.label(
+            doc = "The input file template for header generated in documentation.",
+            allow_single_file = [".vm"],
+            default = Label("//stardoc:templates/header.vm"),
+        ),
+        "func_template": attr.label(
+            doc = "The input file template for functions generated in documentation.",
+            allow_single_file = [".vm"],
+            default = Label("//stardoc:templates/func.vm"),
+        ),
+        "provider_template": attr.label(
+            doc = "The input file template for providers generated in documentation.",
+            allow_single_file = [".vm"],
+            default = Label("//stardoc:templates/provider.vm"),
+        ),
+        "rule_template": attr.label(
+            doc = "The input file template for rules generated in documentation.",
+            allow_single_file = [".vm"],
+            default = Label("//stardoc:templates/rule.vm"),
+        ),
     },
 )
diff --git a/stardoc/templates/func.vm b/stardoc/templates/func.vm
new file mode 100644
index 0000000..9e54006
--- /dev/null
+++ b/stardoc/templates/func.vm
@@ -0,0 +1,36 @@
+<a name="#${funcInfo.functionName}"></a>
+
+#[[##]]# ${funcInfo.functionName}
+
+<pre>
+${util.funcSummary($funcInfo)}
+</pre>
+
+${funcInfo.docString}
+
+#if (!$funcInfo.getParameterList().isEmpty())
+#[[###]]# Parameters
+
+<table class="params-table">
+  <colgroup>
+    <col class="col-param" />
+    <col class="col-description" />
+  </colgroup>
+  <tbody>
+#foreach ($param in $funcInfo.getParameterList())
+    <tr id="${funcInfo.functionName}-${param.name}">
+      <td><code>${param.name}</code></td>
+      <td>
+        ${util.mandatoryString($param)}.#if(!$param.getDefaultValue().isEmpty()) default is <code>$param.getDefaultValue()</code>#end
+
+#if (!$param.docString.isEmpty())
+        <p>
+          ${param.docString.trim()}
+        </p>
+#end
+      </td>
+    </tr>
+#end
+  </tbody>
+</table>
+#end
diff --git a/stardoc/templates/header.vm b/stardoc/templates/header.vm
new file mode 100644
index 0000000..187680d
--- /dev/null
+++ b/stardoc/templates/header.vm
@@ -0,0 +1 @@
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
diff --git a/stardoc/templates/provider.vm b/stardoc/templates/provider.vm
new file mode 100644
index 0000000..b53cccf
--- /dev/null
+++ b/stardoc/templates/provider.vm
@@ -0,0 +1,30 @@
+<a name="#${providerName}"></a>
+
+#[[##]]# ${providerName}
+
+<pre>
+${util.providerSummary($providerName, $providerInfo)}
+</pre>
+
+${providerInfo.docString}
+
+#if (!$providerInfo.fieldInfoList.isEmpty())
+#[[###]]# Fields
+
+<table class="params-table">
+  <colgroup>
+    <col class="col-param" />
+    <col class="col-description" />
+  </colgroup>
+  <tbody>
+#foreach ($field in $providerInfo.fieldInfoList)
+    <tr id="${providerName}-${field.name}">
+      <td><code>${field.name}</code></td>
+      <td>
+        <p>${field.docString}</p>
+      </td>
+    </tr>
+#end
+  </tbody>
+</table>
+#end
diff --git a/stardoc/templates/rule.vm b/stardoc/templates/rule.vm
new file mode 100644
index 0000000..47d1269
--- /dev/null
+++ b/stardoc/templates/rule.vm
@@ -0,0 +1,35 @@
+<a name="#${ruleName}"></a>
+
+#[[##]]# ${ruleName}
+
+<pre>
+${util.ruleSummary($ruleName, $ruleInfo)}
+</pre>
+
+${ruleInfo.docString}
+
+#[[###]]# Attributes
+
+#if (!$ruleInfo.getAttributeList().isEmpty())
+<table class="params-table">
+  <colgroup>
+    <col class="col-param" />
+    <col class="col-description" />
+  </colgroup>
+  <tbody>
+#foreach ($attribute in $ruleInfo.getAttributeList())
+    <tr id="${ruleName}-${attribute.name}">
+      <td><code>${attribute.name}</code></td>
+      <td>
+        ${util.attributeTypeString($attribute)}; ${util.mandatoryString($attribute)}
+#if (!$attribute.docString.isEmpty())
+        <p>
+          ${attribute.docString.trim()}
+        </p>
+#end
+      </td>
+    </tr>
+#end
+  </tbody>
+</table>
+#end
diff --git a/test/self_doc_golden.md b/test/self_doc_golden.md
index a07efe7..937de4b 100755
--- a/test/self_doc_golden.md
+++ b/test/self_doc_golden.md
@@ -5,7 +5,7 @@
 ## stardoc
 
 <pre>
-stardoc(<a href="#stardoc-name">name</a>, <a href="#stardoc-deps">deps</a>, <a href="#stardoc-format">format</a>, <a href="#stardoc-input">input</a>, <a href="#stardoc-out">out</a>, <a href="#stardoc-renderer">renderer</a>, <a href="#stardoc-semantic_flags">semantic_flags</a>, <a href="#stardoc-stardoc">stardoc</a>, <a href="#stardoc-symbol_names">symbol_names</a>)
+stardoc(<a href="#stardoc-name">name</a>, <a href="#stardoc-deps">deps</a>, <a href="#stardoc-format">format</a>, <a href="#stardoc-func_template">func_template</a>, <a href="#stardoc-header_template">header_template</a>, <a href="#stardoc-input">input</a>, <a href="#stardoc-out">out</a>, <a href="#stardoc-provider_template">provider_template</a>, <a href="#stardoc-renderer">renderer</a>, <a href="#stardoc-rule_template">rule_template</a>, <a href="#stardoc-semantic_flags">semantic_flags</a>, <a href="#stardoc-stardoc">stardoc</a>, <a href="#stardoc-symbol_names">symbol_names</a>)
 </pre>
 
 
@@ -49,6 +49,24 @@ This rule is an experimental replacement for the existing skylark_doc rule.
         </p>
       </td>
     </tr>
+    <tr id="stardoc-func_template">
+      <td><code>func_template</code></td>
+      <td>
+        <a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; optional
+        <p>
+          The input file template for functions generated in documentation.
+        </p>
+      </td>
+    </tr>
+    <tr id="stardoc-header_template">
+      <td><code>header_template</code></td>
+      <td>
+        <a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; optional
+        <p>
+          The input file template for header generated in documentation.
+        </p>
+      </td>
+    </tr>
     <tr id="stardoc-input">
       <td><code>input</code></td>
       <td>
@@ -67,6 +85,15 @@ This rule is an experimental replacement for the existing skylark_doc rule.
         </p>
       </td>
     </tr>
+    <tr id="stardoc-provider_template">
+      <td><code>provider_template</code></td>
+      <td>
+        <a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; optional
+        <p>
+          The input file template for providers generated in documentation.
+        </p>
+      </td>
+    </tr>
     <tr id="stardoc-renderer">
       <td><code>renderer</code></td>
       <td>
@@ -76,6 +103,15 @@ This rule is an experimental replacement for the existing skylark_doc rule.
         </p>
       </td>
     </tr>
+    <tr id="stardoc-rule_template">
+      <td><code>rule_template</code></td>
+      <td>
+        <a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; optional
+        <p>
+          The input file template for rules generated in documentation.
+        </p>
+      </td>
+    </tr>
     <tr id="stardoc-semantic_flags">
       <td><code>semantic_flags</code></td>
       <td>