We have a structure similar to this:
[workspace]/
WORKSPACE
BUILD
macro/
BUILD
macro.bzl
docs/
BUILD
The macro.bzl
use string_flag()
and therefore have this load statement.
load(
"@bazel_skylib//rules:common_settings.bzl",
"string_flag",
)
To be able to generate documentation for the macros in macro.bzl
we must take care of the dependency so we have made 2 bzl_library()
targets in macro/BUILD
:
load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
bzl_library(
name = "macro-deps",
srcs = [
"@bazel_skylib//rules:common_settings.bzl",
],
visibility = ["//visibility:public"],
)
bzl_library(
name = "macro-code",
srcs = [
"macro.bzl",
],
visibility = ["//visibility:public"],
)
In BUILD
below docs
we have gathered all stardoc()
rules.
For the macro above we have the following rule:
load("@bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
stardoc(
name = "config-bool-docs",
out = "config-bool.md",
input = "//macro:macro-code",
symbol_names = ["config_option_bool"],
deps = ["//macro:macro-deps"],
)
This works BUT what we actually would like to have is this:
macro/BUILD
:
load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
bzl_library(
name = "macro-deps",
srcs = [
"@bazel_skylib//rules:common_settings.bzl",
],
)
bzl_library(
name = "macro-code",
srcs = [
"macro.bzl",
],
deps= [
"macro-deps",
],
visibility = ["//visibility:public"],
)
And in docs/BUILD
:
load("@bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
stardoc(
name = "config-bool-docs",
out = "config-bool.md",
input = "//macro:macro-code",
symbol_names = ["config_option_bool"],
)
So that we have the deps
in macro-code
target instead of the stardoc()
target.
Shouldn't that work?
It doesn't build but I think that it should and that this is a bug.
It doesn't follow the usual Bazel way of treating the dependencies
As stated above in docs/BUILD
we have gathered all stardoc()
rules (also for more than the above docs/macro
) .
We think that all dependencies should be stated in BUILD's
where we have the code and those BUILD's
shall provide the public bzl_library()
targets that can be used in the stardoc()
rules in docs/BUILD
. The targets below docs
should not need to keep track of the dependencies.