bazelbuild / bazelbuild/stardoc

Should not require rules to aliased before being documented

Open
#94 5 comments 1 reaction 0 assignees View on GitHub
P4 type: feature request
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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.