Use native starlark_doc_extract rule for doc extraction if it is available
* When available (i.e. in Bazel 7, or in current development Bazel at HEAD), try use the `starlark_doc_extract` native rule for doc extraction instead of the legacy pre-built extraction jar. This behavior can be disabled by passing `use_starlark_doc_extract = False` to the `stardoc` macro.
* Add templates and markdown rendering functionality for repository rule and module extension info protos (which are output by `starlark_doc_extract`).
* Temporary wart: for module extensions, by default we would want the summary blurb to look something like
```
my_ext = use_extension("@my_local_repo//some:file.bzl", "my_ext")
my_ext.tag(foo, bar)
```
but alas, we don't have a good way to get the name of the local repo from Starlark when bzlmod is enabled.
* ... and of course, update tests. Which means in some cases, we have to fork the golden files into current (i.e. `starlark_doc_extract`-enabled) and legacy flavors.
Fixes #69
Fixes #76
Fixes #81
Fixes #123diff --git a/test/stardoc_test.bzl b/test/stardoc_test.bzl
index fc44ba8..f4fc9a9 100644
--- a/test/stardoc_test.bzl
+++ b/test/stardoc_test.bzl
@@ -21,21 +21,27 @@
name,
input_file,
golden_file,
+ legacy_golden_file = None,
+ test_legacy_extractor = True,
deps = [],
test = "default",
**kwargs):
"""Convenience macro for stardoc e2e test suites.
- Each invocation creates four targets:
+ Each invocation creates multiple targets:
1. A sh_test target which verifies that stardoc-built-from-source, when run on an input file,
- creates output matching the contents of a golden file, named "{name}_e2e_test".
- 2. A `stardoc` target which will generate a new golden file given an input file
- with stardoc-built-from-source. This target should be used to regenerate
- the golden file when updating stardoc, named "regenerate_{name}_golden".
+ creates output matching the contents of a golden file, named "{name}_e2e_legacy_test".
+ 2. A `stardoc` target which will generate a new golden file given an input file with the
+ legacy extractor built from Bazel source. This target should be used to regenerate the
+ legacy golden file when updating stardoc, named "regenerate_{name}_legacy_golden".
3 & 4. Targets identical to (1) and (2) except they use the prebuilt-stardoc jar, and
- are named "{name}_e2e_jar_test" and "regenerate_with_jar_{name}_golden".
- 5. A bzl_library target for convenient wrapping of input bzl files, named "{name}_lib".
+ are named "{name}_e2e_jar_legacy_test" and "regenerate_with_jar_{name}_legacy_golden".
+ 5 & 6. Only if the host Bazel supports the `native.starlark_doc_extract` rule: Targets
+ identical to (1) and (2) except they use starlark_doc_extract, and are named "{name}_e2e_test"
+ and "regenerate_{name}_golden". The latter target should be used to regenerate the golden
+ file when updating Stardoc.
+ 7. A bzl_library target for convenient wrapping of input bzl files, named "{name}_lib".
Args:
name: A unique name to qualify the created targets.
@@ -43,36 +49,60 @@
in this test.
golden_file: The label string of the golden file containing the documentation when stardoc
is run on the input file.
+ legacy_golden_file: The label string of the golden file when using the legacy documentation
+ extractor. If `legacy_golden_file` is not set, `golden_file` will be used for both extractors.
+ test_legacy_extractor: Whether to create legacy extractor test targets.
deps: A list of label strings of starlark file dependencies of the input_file.
test: The type of test (default or html_tables).
**kwargs: A dictionary of input template names mapped to template file path for which documentation is generated.
"""
+ if legacy_golden_file == None:
+ legacy_golden_file = golden_file
+
bzl_library(
name = "%s_lib" % name,
srcs = [input_file],
deps = deps,
)
- _create_test_targets(
- test_name = "%s_e2e_test" % name,
- genrule_name = "regenerate_%s_golden" % name,
- lib_name = "%s_lib" % name,
- input_file = input_file,
- golden_file = golden_file,
- stardoc_bin = "@io_bazel//src/main/java/com/google/devtools/build/skydoc:skydoc_deploy.jar",
- test = test,
- **kwargs
- )
- _create_test_targets(
- test_name = "%s_e2e_jar_test" % name,
- genrule_name = "regenerate_with_jar_%s_golden" % name,
- lib_name = "%s_lib" % name,
- input_file = input_file,
- golden_file = golden_file,
- stardoc_bin = "@io_bazel//src/main/java/com/google/devtools/build/skydoc:skydoc_deploy.jar",
- test = test,
- **kwargs
- )
+
+ if test_legacy_extractor:
+ _create_test_targets(
+ test_name = "%s_e2e_legacy_test" % name,
+ genrule_name = "regenerate_%s_legacy_golden" % name,
+ lib_name = "%s_lib" % name,
+ input_file = input_file,
+ golden_file = legacy_golden_file,
+ stardoc_bin = "@io_bazel//src/main/java/com/google/devtools/build/skydoc:skydoc_deploy.jar",
+ test = test,
+ use_starlark_doc_extract = False,
+ **kwargs
+ )
+
+ _create_test_targets(
+ test_name = "%s_e2e_jar_legacy_test" % name,
+ genrule_name = "regenerate_with_jar_%s_legacy_golden" % name,
+ lib_name = "%s_lib" % name,
+ input_file = input_file,
+ golden_file = legacy_golden_file,
+ stardoc_bin = "@io_bazel//src/main/java/com/google/devtools/build/skydoc:skydoc_deploy.jar",
+ test = test,
+ use_starlark_doc_extract = False,
+ **kwargs
+ )
+
+ if hasattr(native, "starlark_doc_extract"):
+ _create_test_targets(
+ test_name = "%s_e2e_test" % name,
+ genrule_name = "regenerate_%s_golden" % name,
+ lib_name = "%s_lib" % name,
+ input_file = input_file,
+ golden_file = golden_file,
+ stardoc_bin = None,
+ test = test,
+ use_starlark_doc_extract = True,
+ **kwargs
+ )
def _create_test_targets(
test_name,
