bazelbuild / bazelbuild/stardoc
deps in bzl_library() incorrect handled in stardoc()
- Dominant language
- Java
- Stars
- 118
- Forks
- 51
- PR merge metrics
- No merged PRs in 30d
Description
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.
```python
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`:
```python
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:
```python
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`:
```python
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`:
```python
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.
Contributor guide
Research direction
Reproduce the issue with the shown WORKSPACE, macro/BUILD, macro/macro.bzl, and docs/BUILD structure. Start by comparing the working stardoc(deps = ["//macro:macro-deps"]) configuration with the failing bzl_library(deps = ["macro-deps"]) configuration. Done means the dependency declared by macro-code is correctly available to stardoc without duplicating it in docs/BUILD.
Written by the indexing model from the issue text.
Assessment
- Domain
- build-system
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100