Better support for stardoc usage in another directory from the bzl files

[thomasvl]

It seems like it would make sense to put your stardoc() rules in a docs directory where you check in the generated files. But to do that you also have to export the *.bzl files if it has dependencies because the bzl_library will have more that one file in it. Ideally the rule would support a bzl_library as input where there is only one direct src entry, or it should support a raw string that isn't a label so the deps of the bzl_library could tell it which file to act on.

[thomasvl]

Looks like the problem is input is a attr.label(), so it won't accept something that expands to >1 file even though the StarlarkLibraryInfo provider has the distinction between srcs and transitive_srcs.

Any ideas how this can be improved to make using the stardoc rule easier from a different directory that the bzl files?

[brandjon]

I think with #69 it'll be moot anyway. I imagine you'd effectively be querying the documentation of a bzl file by giving its label, regardless of visibility.

[thomasvl]

I'm not sure I follow how #69 helps? Since the stardoc rule takes a label that has to expand to a single file, it can't ever reference a bzl_library instance when the file has dependencies. So you have to export the individual bzl file and use the bzl_library as the deps. This was saying it would be nice bzl_library exposed both direct and transitive sources so stardoc could know the direct file and work with that one bzl_library reference.

[brandjon]

What I was getting at was that you'd end up generating a file (a la genquery) that includes extracted documentation, and that file would become the input to the rendering side of things (though perhaps both steps would be wrapped up in a common macro). Transitive information is no longer needed at that point.

[thomasvl]

Ah, I guess it will depend on if there is still a stardoc rule to do the generation? If says a genquery is used as input to that rule, then the similar flows/locations/visibility might also come into play. Thanks.

[brandjon]

We'd only want the actual extraction to be built into Bazel. What you do with that information in terms of rendering, resolving labels to hyperlinks, etc., should be customizable and would almost certainly still live in the Stardoc repo.

Since the genquery-like output could be produced without regard to visibility of .bzl files, you'd only need that one file to be visible as input to the stardoc rule, and the stardoc rule would have on need to consume transitive info that it is not presently generating documentation for (although it would have to resolve references to such things into hyperlinks).