Should not require rules to aliased before being documented

[shs96c]

When following the instructions for documenting 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.

[brandjon]

This is because loaded symbols are private to the file that loads them, unlike assigned global variables which are considered part of the module object defined by the .bzl file. So they're invisible to Stardoc.

This will still be the case even after the rewrite of Stardoc to use a bazel query style approach.

What I wonder is why are you loading these symbols if you don't also want to export them. I'd suggest that either you continue to assign _foo_rule to foo_rule, so that this .bzl file becomes both a public entry point to load and also a place to point stardoc; or else you instead point stardoc at foo.bzl, bar.bzl, etc.

[Kernald]

What I wonder is why are you loading these symbols if you don't also want to export them. I'd suggest that either you continue to assign _foo_rule to foo_rule, so that this .bzl file becomes both a public entry point to load and also a place to point stardoc; or else you instead point stardoc at foo.bzl, bar.bzl, etc.

The current stardoc rule only allows for one input file, doesn't it? It sometimes makes sense exposing multiple rules/macros in a single documentation page. I just hit the same issue trying to do just that. I'm not sure it's a totally legitimate use-case as I'm not entirely sure what I want to do with those docs, and maybe I don't want to do it this way, but that's how I encountered this issue as well. As a sidenote, the documentation should at least be updated to reflect this.

[tetromino]

The current stardoc rule only allows for one input file, doesn't it? It sometimes makes sense exposing multiple rules/macros in a single documentation page.

This is difficult to do well in the general case.

• Each .bzl file will have its own module docstring at the top of the file. How do you render those multiple docstrings in a single markdown file in a way that is not confusing?
• How do you inform your reader which symbol is exported by which .bzl file?
• How do you handle aliasing, where the same symbol is exported by two different .bzl files under different names?

And if you don't want to do it well in the general case, if your use case is very simple, you can just write a genrule to concatenate the markdown output of two stardoc rules :)

[adam-azarchs]

Aliasing was a bit annoying but not a real problem in older versions of stardoc. However in newer versions, you end up with documentation like

load("@//:rules_doc.bzl", "my_rule")

rather than the correct

load("@//:my_rule.bzl", "my_rule")

I agree concatenation of the output markdown is probably the better way to go here, but then maybe https://github.com/bazelbuild/stardoc/blob/master/docs/generating_stardoc.md#multiple-files should be updated.