How to generate documentation for multiple files with Stardoc?

Question

I'm not able to generate documentation for multiple bazel rules in separate files with Stardoc 0.3.0 and Bazel 0.24.1.

This is my setup. There are three bazel rules in separate files.

BUILD

bzl_library(
    name = "bzl",
    srcs = ["antlr2.bzl", "antlr3.bzl", "antlr4.bzl"],
    deps = [
        "@bazel_skylib//:bzl_library",
    ],
)
stardoc(
    name = "single-docs",
    input = "antlr2.bzl",
    out = "antlr2_single.md",
)
stardoc(
    name = "multi-docs",
    input = "doc.bzl",
    out = "doc.md",
    deps = [":bzl"],
)

And one file to load them:

doc.bzl

load("//antlr:antlr2.bzl", "antlr2")
load("//antlr:antlr3.bzl", "antlr3")
load("//antlr:antlr4.bzl", "antlr4")

It builds, but the generated file is essentially empty:

doc.md

<!-- Generated with Stardoc: http://skydoc.bazel.build -->

If I do what the documentation suggests:

BUILD

...
stardoc(
    name = "multi-docs",
    input = "doc.bzl",
    out = "doc.md",
)

I receive an error:

Exception in thread "main" java.lang.IllegalStateException: File antlr/doc.bzl imported '//antlr:antlr2.bzl', yet antlr/antlr2.bzl was not found, even at roots [.].
    at com.google.devtools.build.skydoc.SkydocMain.recursiveEval(SkydocMain.java:420)
    at com.google.devtools.build.skydoc.SkydocMain.eval(SkydocMain.java:338)
    at com.google.devtools.build.skydoc.SkydocMain.main(SkydocMain.java:205)
Caused by: java.nio.file.NoSuchFileException: antlr/antlr2.bzl
    at com.google.devtools.build.skydoc.SkydocMain.getInputSource(SkydocMain.java:453)
    at com.google.devtools.build.skydoc.SkydocMain.recursiveEval(SkydocMain.java:404)
    at com.google.devtools.build.skydoc.SkydocMain.recursiveEval(SkydocMain.java:416)
    ... 2 more

Am I doing something wrong or is this a bug?

BTW, the single file target single-docs generates correctly.

Answer 1

I finally figured it out. Don't know whether this is something that's gonna be changed/fixed in the future or just not yet properly documented: You have to alias the rules!

doc.bzl

load("//antlr:antlr4.bzl", _antlr4 = "antlr4")  
load("//antlr:antlr2.bzl", _antlr2 = "antlr2")  
load("//antlr:antlr3.bzl", _antlr3 = "antlr3")  

antlr4 = _antlr4  
antlr3 = _antlr3  
antlr2 = _antlr2