Generate markdown output by piping the stardoc proto output through the renderer binary

3 files changed, 84 insertions, 21 deletions

diff --git a/stardoc/BUILD b/stardoc/BUILD
index c72baa5..d7e7b2f 100644
--- a/stardoc/BUILD
+++ b/stardoc/BUILD
@@ -54,3 +54,25 @@ java_import(
     jars = ["stardoc_binary.jar"],
     visibility = ["//visibility:private"],
 )
+
+java_binary(
+    name = "renderer",
+    jvm_flags = [
+        # quiet warnings from com.google.protobuf.UnsafeUtil,
+        # see: https://github.com/google/protobuf/issues/3781
+        # TODO(cparsons): Remove once Stardoc has the fix.
+        "-XX:+IgnoreUnrecognizedVMOptions",
+        "--add-opens=java.base/java.nio=ALL-UNNAMED",
+        "--add-opens=java.base/java.lang=ALL-UNNAMED",
+    ],
+    main_class = "com.google.devtools.build.skydoc.renderer.RendererMain",
+    runtime_deps = [
+        ":prebuilt_renderer_binary",
+    ],
+)
+
+java_import(
+    name = "prebuilt_renderer_binary",
+    jars = ["renderer_binary.jar"],
+    visibility = ["//visibility:private"],
+)
diff --git a/stardoc/stardoc.bzl b/stardoc/stardoc.bzl
index f22ac89..ed9a8a7 100644
--- a/stardoc/stardoc.bzl
+++ b/stardoc/stardoc.bzl
@@ -30,12 +30,11 @@ def _stardoc_impl(ctx):
         dep[StarlarkLibraryInfo].transitive_srcs
         for dep in ctx.attr.deps
     ])
-    args = ctx.actions.args()
-    args.add("--input=" + str(ctx.file.input.owner))
-    args.add("--output=" + ctx.outputs.out.path)
-    args.add("--workspace_name=" + ctx.workspace_name)
-    args.add("--output_format=" + ctx.attr.format)
-    args.add_all(
+    stardoc_args = ctx.actions.args()
+    stardoc_args.add("--input=" + str(ctx.file.input.owner))
+    stardoc_args.add("--workspace_name=" + ctx.workspace_name)
+    stardoc_args.add("--output_format=proto")
+    stardoc_args.add_all(
         ctx.attr.symbol_names,
         format_each = "--symbols=%s",
         omit_if_empty = True,
@@ -48,25 +47,53 @@ def _stardoc_impl(ctx):
     # disabled). The correct way to resolve this is to explicitly specify
     # the full set of transitive dependency Starlark files as action args
     # (maybe using a param file), but this requires some work.
-    args.add_all(
+    stardoc_args.add_all(
         input_files,
         format_each = "--dep_roots=%s",
         map_each = _root_from_file,
         omit_if_empty = True,
         uniquify = True,
     )
-    args.add_all(ctx.attr.semantic_flags)
+    stardoc_args.add_all(ctx.attr.semantic_flags)
     stardoc = ctx.executable.stardoc
-    ctx.actions.run(
-        outputs = [out_file],
-        inputs = input_files,
-        executable = stardoc,
-        arguments = [args],
-        mnemonic = "Stardoc",
-        progress_message = ("Generating Starlark doc for %s" %
-                            (ctx.label.name)),
-    )
-
+    
+    if ctx.attr.format == "proto":
+        stardoc_args.add("--output=" + out_file)
+        ctx.actions.run(
+            outputs = [out_file],
+            inputs = input_files,
+            executable = stardoc,
+            arguments = [stardoc_args],
+            mnemonic = "Stardoc",
+            progress_message = ("Generating Starlark doc for %s" %
+                                (ctx.label.name)),
+        )
+    elif ctx.attr.format == "markdown":
+        proto_file = ctx.actions.declare_file(ctx.label.name + ".raw", sibling = out_file)
+        stardoc_args.add("--output=" + proto_file.path)
+        ctx.actions.run(
+            outputs = [proto_file],
+            inputs = input_files,
+            executable = stardoc,
+            arguments = [stardoc_args],
+            mnemonic = "Stardoc",
+            progress_message = ("Generating proto for Starlark doc for %s" %
+                                (ctx.label.name)),
+        )
+        renderer_args = ctx.actions.args()
+        renderer_args.add("--input=" + str(proto_file.path))
+        renderer_args.add("--output=" + str(ctx.outputs.out.path))
+        renderer = ctx.executable.renderer
+        ctx.actions.run(
+            outputs = [out_file],
+            inputs = [proto_file],
+            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 = """
@@ -118,5 +145,12 @@ non-default semantic flags required to use the given Starlark symbols.
             cfg = "host",
             executable = True,
         ),
+        "renderer": attr.label(
+            doc = "The location of the renderer tool.",
+            allow_files = True,
+            default = Label("//stardoc:renderer"),
+            cfg = "host",
+            executable = True,
+        ),
     },
 )
diff --git a/test/self_doc_golden.md b/test/self_doc_golden.md
index dae7e1f..bfb1255 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-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-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>)
 </pre>
 
 
@@ -67,6 +67,15 @@ This rule is an experimental replacement for the existing skylark_doc rule.
         </p>
       </td>
     </tr>
+    <tr id="stardoc-renderer">
+      <td><code>renderer</code></td>
+      <td>
+        <a href="https://bazel.build/docs/build-ref.html#labels">Label</a>; optional
+        <p>
+          The location of the renderer tool.
+        </p>
+      </td>
+    </tr>
     <tr id="stardoc-semantic_flags">
       <td><code>semantic_flags</code></td>
       <td>
@@ -104,7 +113,6 @@ documentation for all exported rule definitions will be generated.
   </tbody>
 </table>
 
-
 <a name="#_stardoc_impl"></a>
 
 ## _stardoc_impl
@@ -132,4 +140,3 @@ Implementation of the stardoc rule.
   </tbody>
 </table>
 
-