Stardoc cannot handle input files from remote repositories

[apekter]

Idea: Create a bazel project for the purpose of documenting another bazel project. The main reason of this approach is to separate the project dependencies from the documentation dependencies as well as to have the capabilities to document multiple projects at once.

Issue: Stardoc rules cannot handle .bzl files from remote repositories. The result of running the build is the following error:

C:\work\doc_repo>bazel build //:docs --incompatible_disallow_data_transition=false --subcommands --verbose_failures
INFO: Analysed target //:docs (1 packages loaded, 3 targets configured).
INFO: Found 1 target...
SUBCOMMAND: # //:gen_rule_doc [action 'Generating Starlark doc for gen_rule_doc']
cd C:/users/xxxx/_bazel_xxxx/4ip5ddub/execroot/doc_repo
bazel-out/host/bin/external/io_bazel/src/main/java/com/google/devtools/build/skydoc/skydoc.exe --input=@remote//bazel:gen_rule.bzl --output=bazel-out/x64_windows-fastbuild/
bin/gen_rule.md
ERROR: C:/work/doc_repo/BUILD:10:1: Generating Starlark doc for gen_rule_doc failed (Exit 1): skydoc.exe failed: error executing command
  cd C:/users/xxxx/_bazel_xxxx/4ip5ddub/execroot/doc_repo
bazel-out/host/bin/external/io_bazel/src/main/java/com/google/devtools/build/skydoc/skydoc.exe --input=@remote//bazel:gen_rule.bzl --output=bazel-out/x64_windows-fastbuild/
bin/gen_rule.md
Execution platform: @bazel_tools//platforms:host_platform
Exception in thread "main" java.lang.IllegalStateException: File external\remote\bazel\utils.bzl imported '@bazel_skylib//lib:collections.bzl', yet external\bazel_skylib\lib\
collections.bzl was not found.
        at com.google.devtools.build.skydoc.SkydocMain.recursiveEval(SkydocMain.java:406)
        at com.google.devtools.build.skydoc.SkydocMain.recursiveEval(SkydocMain.java:402)
        at com.google.devtools.build.skydoc.SkydocMain.eval(SkydocMain.java:327)
        at com.google.devtools.build.skydoc.SkydocMain.main(SkydocMain.java:190)
Target //:docs failed to build
INFO: Elapsed time: 2.459s, Critical Path: 1.69s
INFO: 0 processes.
FAILED: Build did NOT complete successfully

C:\work\doc_repo>

[c-parsons]

Stardoc can indeed handle .bzl files from remote repositories. Can you provide some more details on how to reproduce this error? As an example, Stardoc self-documents its Starlark rule (stardoc.bzl), and directly depends on @bazel_skylib.

It's important you specify the dependencies of the bzl files you want to generate documentation for. See this example.

[apekter]

You are correct about a case where you load a rule from a .bzl file from a remote repo and use it a s a dependency. What I am trying to do is to have a stardoc rule that uses a .bzl file directly from a remote repo as input without loading it for example:

stardoc(
    name = "my_rule_doc", 
    input = "@remote_repo//custom_rules/bazel:my_rule.bzl", 
    out = "my_rule_doc.md",
    visibility = ["//visibility:public"], 
)

[c-parsons]

Aha. I'll take a look. Thanks for the info.

[brandjon]

The main reason of this approach is to separate the project dependencies from the documentation dependencies as well as to have the capabilities to document multiple projects at once.

For the first part, it might be enough to separate the documentation targets into separate packages within your main repo. The idea is that you might avoid loading any packages that cause documentation dependencies to be downloaded. Admittedly that doesn't address the possible bug we're talking about.

Chris, do you recall anything about this issue? Is this kind of use case supported?