bazelbuild / bazelbuild/stardoc

Stardoc cannot handle input files from remote repositories

Open
#29 4 comments 0 reactions 0 assignees View on GitHub
P3 type: bug
Dominant language
Java
Stars
118
Forks
51
PR merge metrics
No merged PRs in 30d

Description

_**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>
```

Contributor guide

Open the contributing guide

Research direction

Start with the BUILD target //:docs and the skydoc command shown in the failure, then read the SkydocMain.java locations named in the stack trace. Reproduce the remote @remote//bazel:gen_rule.bzl case and inspect how its @bazel_skylib import is resolved. Done means the documented remote .bzl input builds and produces gen_rule.md without the missing-file error.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
build-system, documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.