From bf6632e1597e6cb01f5a31bf9506a1463c15385b Mon Sep 17 00:00:00 2001
From: Fabian Meumertzheim <fabian@meumertzhe.im>
Date: Fri, 28 Apr 2023 13:18:39 +0200
Subject: [PATCH] Allow stardoc to be a java_binary or jar
---
docs/stardoc_rule.md | 4 ++--
stardoc/BUILD | 2 +-
stardoc/stardoc.bzl | 29 +++++++++++++++++++++++++----
3 files changed, 28 insertions(+), 7 deletions(-)
diff --git a/docs/stardoc_rule.md b/docs/stardoc_rule.md
index 2532abe1..ce4e3cb3 100644
--- a/docs/stardoc_rule.md
+++ b/docs/stardoc_rule.md
@@ -25,8 +25,8 @@ Generates documentation for exported starlark rule definitions in a target starl
| <a id="stardoc-format"></a>format | The format of the output file. Valid values: 'markdown' or 'proto'. | <code>"markdown"</code> |
| <a id="stardoc-symbol_names"></a>symbol_names | A list of symbol names to generate documentation for. These should correspond to the names of rule definitions in the input file. If this list is empty, then documentation for all exported rule definitions will be generated. | <code>[]</code> |
| <a id="stardoc-semantic_flags"></a>semantic_flags | A list of canonical flags to affect Starlark semantics for the Starlark interpreter during documentation generation. This should only be used to maintain compatibility with non-default semantic flags required to use the given Starlark symbols.<br><br>For example, if <code>//foo:bar.bzl</code> does not build except when a user would specify <code>--incompatible_foo_semantic=false</code>, then this attribute should contain "--incompatible_foo_semantic=false". | <code>[]</code> |
-| <a id="stardoc-stardoc"></a>stardoc | The location of the stardoc tool. | <code>Label("//stardoc:prebuilt_stardoc_binary")</code> |
-| <a id="stardoc-renderer"></a>renderer | The location of the renderer tool. | <code>Label("//stardoc:renderer")</code> |
+| <a id="stardoc-stardoc"></a>stardoc | The location of the stardoc tool (a <code>java_binary</code> target or a <code>.jar</code> file). | <code>Label("//stardoc:stardoc")</code> |
+| <a id="stardoc-renderer"></a>renderer | The location of the renderer tool (a <code>java_binary</code> target or a <code>.jar</code> file). | <code>Label("//stardoc:renderer")</code> |
| <a id="stardoc-aspect_template"></a>aspect_template | The input file template for generating documentation of aspects | <code>Label("//stardoc:templates/markdown_tables/aspect.vm")</code> |
| <a id="stardoc-func_template"></a>func_template | The input file template for generating documentation of functions. | <code>Label("//stardoc:templates/markdown_tables/func.vm")</code> |
| <a id="stardoc-header_template"></a>header_template | The input file template for the header of the output documentation. | <code>Label("//stardoc:templates/markdown_tables/header.vm")</code> |
diff --git a/stardoc/BUILD b/stardoc/BUILD
index 045774ff..8a8c6789 100644
--- a/stardoc/BUILD
+++ b/stardoc/BUILD
@@ -60,7 +60,7 @@ java_binary(
java_import(
name = "prebuilt_stardoc_binary",
jars = ["stardoc_binary.jar"],
- visibility = ["//visibility:public"],
+ visibility = ["//visibility:private"],
)
java_binary(
diff --git a/stardoc/stardoc.bzl b/stardoc/stardoc.bzl
index 1728dfc1..03fdd342 100644
--- a/stardoc/stardoc.bzl
+++ b/stardoc/stardoc.bzl
@@ -26,7 +26,7 @@ def stardoc(
format = "markdown",
symbol_names = [],
semantic_flags = [],
- stardoc = Label("//stardoc:prebuilt_stardoc_binary"),
+ stardoc = Label("//stardoc"),
renderer = Label("//stardoc:renderer"),
aspect_template = Label("//stardoc:templates/markdown_tables/aspect.vm"),
func_template = Label("//stardoc:templates/markdown_tables/func.vm"),
@@ -52,8 +52,8 @@ def stardoc(
For example, if `//foo:bar.bzl` does not build except when a user would specify
`--incompatible_foo_semantic=false`, then this attribute should contain
"--incompatible_foo_semantic=false".
- stardoc: The location of the stardoc tool.
- renderer: The location of the renderer tool.
+ stardoc: The location of the stardoc tool (a `java_binary` target or a `.jar` file).
+ renderer: The location of the renderer tool (a `java_binary` target or a `.jar` file).
aspect_template: The input file template for generating documentation of aspects
header_template: The input file template for the header of the output documentation.
func_template: The input file template for generating documentation of functions.
@@ -68,7 +68,9 @@ def stardoc(
java_binary(
name = stardoc_with_runfiles_name,
main_class = "com.google.devtools.build.skydoc.SkydocMain",
- runtime_deps = [stardoc],
+ # java_binary targets cannot be added as deps of a java_binary, so we may need to get the
+ # corresponding _deploy.jar target.
+ runtime_deps = [_get_deploy_jar_label_if_not_jar(stardoc)],
data = [input] + deps,
tags = ["manual"],
visibility = ["//visibility:private"],
@@ -91,3 +93,22 @@ def stardoc(
rule_template = rule_template,
**kwargs
)
+
+def _get_deploy_jar_label_if_not_jar(label):
+ """Returns the label of the _deploy.jar target corresponding to the given java_binary label."""
+
+ # label could be a string or a Label.
+ label_str = str(label)
+
+ # Convert "@my_stardoc" to "@my_stardoc//:my_stardoc".
+ if not "//" in label_str:
+ if not label_str.startswith("@"):
+ fail("Invalid label: %s" % label_str)
+ label_str = label_str + "//:" + label_str[1]
+ if not ":" in label_str:
+ label_str = label_str + ":" + label_str.split("/")[-1]
+
+ if label_str.endswith(".jar"):
+ return label_str
+ else:
+ return label_str + "_deploy.jar"