bazelbuild / bazelbuild/stardoc
Should not require rules to aliased before being documented
- Dominant language
- Java
- Stars
- 118
- Forks
- 51
- PR merge metrics
- No merged PRs in 30d
Description
When following the instructions for [documenting multiple files](https://github.com/bazelbuild/stardoc/blob/master/docs/generating_stardoc.md#multiple-files) the generated docs are empty. In order for content to be created, the rules need to aliased in some way.
That is, attempting to generate docs from the following will lead to an empty doc:
```
load("//foo:foo.bzl", "foo_rule")
load("//bar:bar.bzl", "bar_rule")
load("//baz:baz.bzl", "baz_rule")
```
Whereas:
```
load("//foo:foo.bzl", _foo_rule = "foo_rule")
load("//bar:bar.bzl", _bar_rule = "bar_rule")
load("//baz:baz.bzl", _baz_rule = "baz_rule")
foo_rule = _foo_rule
bar_rule = _bar_rule
baz_rule = _baz_rule
```
will lead to the expected documentation being generated. This is confusing and unexpected. In addition, many authors don't want to expose all the rules this way.
Contributor guide
Research direction
Start with the multiple-files instructions in docs/generating_stardoc.md and reproduce the empty output using the unaliased load statements from the issue. Trace the documentation-generation entry point to determine why directly loaded rules are omitted; done means those rules are documented without alias assignments.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100