bazelbuild / bazelbuild/stardoc

deps in bzl_library() incorrect handled in stardoc()

Open
#72 6 comments 0 reactions 0 assignees View on GitHub
P4 type: bug
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.