Stardoc doesn't handle generated bzl dependencies

[c-parsons]

If, in a transitive bzl_library dependency, one of the sources is generated, the input file to stardoc instead of living under the workspace lives under bazel-out instead of relative to the execution root. Stardoc thus has no idea where to find it.

For example, a proper input file path looks like:

foo/bar.bzl

But a generated input file path looks like:

bazel-out/k8-opt/bin/foo/bar.bzl

My plan here is:

1. Modify Stardoc binary to take a new optional flag, "--dep_roots" each entry represents a root path directory to evaluate dependencies. To fix the example in Commit 4b71d2e1bc3afa0ce0a5b6e68dac3c559654d975 of Bazel enforce workspace name which breaks skydoc #7, we would pass --dep_roots=bazel-out/k8-opt/bin

   Stardoc will thus, when looking for a bzl file across a transitive dependency, try:

   1. Finding the dependency rooted at an entry of dep_roots, in order
   2. Finding the dependency rooted at the current directory
   3. Giving up and throwing an exception

2. Modify the stardoc Starlark rule to include values of --dep_roots to the invocation of the Stardoc binary. These arguments will be added with:

def _root_from_path(f):
     return f.root.path

def _stardoc_impl(ctx)
      ...
      args = ctx.actions.args()
      args.add_joined("--dep_roots=", inputs,
          join_with = ","
          map_each = _root_from_path,
          omit_if_empty = True, 
          uniquify = True)
     ...

[laurentlb]

The plan looks good.
Do we have use-cases for generated bzl files? Bazel users won't be able to load them.

[c-parsons]

Correct -- the use case is a team which exposes a bzl_library which explicitly stubs out their "real" rules. This team's users write macros pointing to the team's rules. When these users want to test their own macros, the team encourages their users to depend on the "stub" bzl_library instead of the "real" implementation.

It's a little backwards, but since bzl_library does technically allow generated files, we should have Stardoc handle this case nicely.