From 626af72fe87bc8a428d6d5dcd1e551a7464dc0db Mon Sep 17 00:00:00 2001 From: Alex Eagle Date: Wed, 27 Apr 2022 17:22:30 -0700 Subject: [PATCH] test: add test coverage for docs rules --- .prettierignore | 1 + MODULE.bazel | 1 + docs/docs.md | 9 ++------- e2e/bzlmod/.bazelrc | 1 - e2e/bzlmod/BUILD.bazel | 27 ++++++++++++++++++++++++++- e2e/bzlmod/WORKSPACE | 2 ++ e2e/bzlmod/defs.bzl | 1 + e2e/bzlmod/docs.md | 4 ++++ lib/private/docs.bzl | 20 ++++---------------- 9 files changed, 41 insertions(+), 25 deletions(-) create mode 100644 e2e/bzlmod/defs.bzl create mode 100644 e2e/bzlmod/docs.md diff --git a/.prettierignore b/.prettierignore index 5e4027f..51ed124 100644 --- a/.prettierignore +++ b/.prettierignore @@ -1,4 +1,5 @@ docs/*.md +e2e/*/docs.md lib/tests/jq/*.json lib/tests/yq/empty.yaml lib/lib/tests/write_source_files/*.js diff --git a/MODULE.bazel b/MODULE.bazel index 4883d2c..46b5067 100644 --- a/MODULE.bazel +++ b/MODULE.bazel @@ -12,6 +12,7 @@ module( bazel_dep(name = "bazel_skylib", version = "1.1.1") bazel_dep(name = "platforms", version = "0.0.4") +bazel_dep(name = "stardoc", version = "0.5.0", repo_name = "io_bazel_stardoc") ext = use_extension("@aspect_bazel_lib//lib:extensions.bzl", "ext") use_repo(ext, "jq_toolchains") diff --git a/docs/docs.md b/docs/docs.md index 793db71..d2e4c8a 100644 --- a/docs/docs.md +++ b/docs/docs.md @@ -7,8 +7,7 @@ Public API for docs helpers ## stardoc_with_diff_test 
-stardoc_with_diff_test(name, bzl_library_target, aspect_template, func_template, header_template,
-                       provider_template, rule_template, suggested_update_target)
+stardoc_with_diff_test(name, bzl_library_target, suggested_update_target, kwargs)
Creates a stardoc target, diff test, and an executable to rule to write the generated doc to the source tree and test that it's up to date. @@ -23,12 +22,8 @@ This is helpful for minimizing boilerplate in repos wih lots of stardoc targets. | :------------- | :------------- | :------------- | | name | the name of the stardoc file to be written to the current source directory (.md will be appended to the name). Call bazel run on this target to update the file. | none | | bzl_library_target | the label of the bzl_library target to generate documentation for | none | -| aspect_template | the label or path to the Velocity aspect template to use with stardoc | "@io_bazel_stardoc//stardoc:templates/markdown_tables/aspect.vm" | -| func_template | the label or path to the Velocity function/macro template to use with stardoc | "@io_bazel_stardoc//stardoc:templates/markdown_tables/func.vm" | -| header_template | the label or path to the Velocity header template to use with stardoc | "@io_bazel_stardoc//stardoc:templates/markdown_tables/header.vm" | -| provider_template | the label or path to the Velocity provider template to use with stardoc | "@io_bazel_stardoc//stardoc:templates/markdown_tables/provider.vm" | -| rule_template | the label or path to the Velocity rule template to use with stardoc | "@io_bazel_stardoc//stardoc:templates/markdown_tables/rule.vm" | | suggested_update_target | the target suggested to be run when a doc is out of date (should be the label for [update_docs](#update_docs)) | "//docs:update" | +| kwargs | additional attributes passed to the stardoc() rule, such as for overriding the templates | none | diff --git a/e2e/bzlmod/.bazelrc b/e2e/bzlmod/.bazelrc index ed153f0..b3a24e8 100644 --- a/e2e/bzlmod/.bazelrc +++ b/e2e/bzlmod/.bazelrc @@ -1,2 +1 @@ common --experimental_enable_bzlmod -common --registry=https://raw.githubusercontent.com/aspect-build/bazel-central-registry/main/ \ No newline at end of file diff --git a/e2e/bzlmod/BUILD.bazel b/e2e/bzlmod/BUILD.bazel index 6b02430..f169fe2 100644 --- a/e2e/bzlmod/BUILD.bazel +++ b/e2e/bzlmod/BUILD.bazel @@ -1,7 +1,32 @@ +"""Integration testing that aspect_bazel_lib works when used via bzlmod. + +NB: We don't use yq, so we can confirm that Bazel never fetches it. +You can manually verify this after testing this repo with +`ls $(bazel info output_base)/external | grep yq` +You'll see a aspect_bazel_lib.ext.yq_toolchains repo, but no downloaded yq binary. +""" + load("@aspect_bazel_lib//lib:jq.bzl", "jq") +load("@aspect_bazel_lib//lib:docs.bzl", "stardoc_with_diff_test") +load("@bazel_skylib//:bzl_library.bzl", "bzl_library") load("@bazel_skylib//rules:diff_test.bzl", "diff_test") -# No sources produces null (equivalent to --null-input) +bzl_library( + name = "defs", + srcs = ["defs.bzl"], +) + +# Validate that stardoc dependency works. +# Note, stardoc is generally broken under bzlmod, see +# https://github.com/bazelbuild/stardoc/issues/117 +# This happens to work because we don't reference any external repos +# from defs.bzl. +stardoc_with_diff_test( + name = "docs", + bzl_library_target = "//:defs", +) + +# Validate that JQ works and resolves its toolchain jq( name = "case_no_sources", srcs = [], diff --git a/e2e/bzlmod/WORKSPACE b/e2e/bzlmod/WORKSPACE index e69de29..79d35f9 100644 --- a/e2e/bzlmod/WORKSPACE +++ b/e2e/bzlmod/WORKSPACE @@ -0,0 +1,2 @@ +# Marker file that this folder is the root of a Bazel workspace. +# See MODULE.bazel for dependencies and setup. diff --git a/e2e/bzlmod/defs.bzl b/e2e/bzlmod/defs.bzl new file mode 100644 index 0000000..433dbb4 --- /dev/null +++ b/e2e/bzlmod/defs.bzl @@ -0,0 +1 @@ +# no rules diff --git a/e2e/bzlmod/docs.md b/e2e/bzlmod/docs.md new file mode 100644 index 0000000..cfc972b --- /dev/null +++ b/e2e/bzlmod/docs.md @@ -0,0 +1,4 @@ + + + + diff --git a/lib/private/docs.bzl b/lib/private/docs.bzl index 4ac00db..4e5e369 100644 --- a/lib/private/docs.bzl +++ b/lib/private/docs.bzl @@ -6,12 +6,8 @@ load("//lib:write_source_files.bzl", "write_source_files") def stardoc_with_diff_test( name, bzl_library_target, - aspect_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/aspect.vm", - func_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/func.vm", - header_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/header.vm", - provider_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/provider.vm", - rule_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/rule.vm", - suggested_update_target = "//docs:update"): + suggested_update_target = "//docs:update", + **kwargs): """Creates a stardoc target, diff test, and an executable to rule to write the generated doc to the source tree and test that it's up to date. This is helpful for minimizing boilerplate in repos wih lots of stardoc targets. @@ -19,12 +15,8 @@ def stardoc_with_diff_test( Args: name: the name of the stardoc file to be written to the current source directory (.md will be appended to the name). Call bazel run on this target to update the file. bzl_library_target: the label of the `bzl_library` target to generate documentation for - aspect_template: the label or path to the Velocity aspect template to use with stardoc - func_template: the label or path to the Velocity function/macro template to use with stardoc - header_template: the label or path to the Velocity header template to use with stardoc - provider_template: the label or path to the Velocity provider template to use with stardoc - rule_template: the label or path to the Velocity rule template to use with stardoc suggested_update_target: the target suggested to be run when a doc is out of date (should be the label for [update_docs](#update_docs)) + **kwargs: additional attributes passed to the stardoc() rule, such as for overriding the templates """ stardoc_label = name + "-docgen" @@ -36,12 +28,8 @@ def stardoc_with_diff_test( out = name + "-docgen.md", input = bzl_library_target + ".bzl", deps = [bzl_library_target], - aspect_template = aspect_template, - func_template = func_template, - header_template = header_template, - provider_template = provider_template, - rule_template = rule_template, tags = ["package:" + native.package_name()], # Tag the package name which will help us reconstruct the write_source_files label in update_docs + **kwargs ) write_source_files(