Как создать документацию для нескольких файлов с помощью Stardoc? - PullRequest
Новая
       11

Как создать документацию для нескольких файлов с помощью Stardoc?

0 голосов
/ 18 апреля 2019

Я не могу сгенерировать документацию для нескольких правил Bazel в отдельных файлах с Stardoc 0.3.0 и Bazel 0.24.1.

Это мои настройки. В отдельных файлах есть три правила Bazel.

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"],
)

И один файл для их загрузки:

doc.bzl

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

Он собирается, но сгенерированный файл практически пустой:

doc.md

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

Если я делаю то, что предлагает документация:

BUILD

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

Я получаю сообщение об ошибке: 

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

Я что-то не так делаю или это ошибка?

Кстати, один файл цели single-docs генерирует правильно.

1 Ответ

1 голос
/ 29 мая 2019

Я наконец понял это. Не знаю, будет ли это что-то, что будет изменено / исправлено в будущем, или просто еще не документировано должным образом: вы должны сделать псевдоним правил!

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
...