search

bazelbuild / stardoc

Stardoc: Starlark Documentation Generator
Apache License 2.0
108 stars 45 forks source link

stardoc fails to generate documentation for module extensions #123

Closed nathaniel-brough closed 1 year ago

nathaniel-brough commented 2 years ago

Stardoc fails when trying to generate documentation for a bzlmod extension;

Steps to reproduce;

Create a module extension;

# //:some_module.bzl
some_tag = tag_class(attrs = {
    "path": attr.string(),
    "id": attr.string(),
})

def foo_impl(module_ctx):
    pass

foo = module_extension(
    implementation = foo_impl,
    tag_classes = {"foo_tag": some_tag},
)

Then attempt to generate docs for the module extension;

# //:BUILD.bazel
load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")

stardoc(
    name = "module_doc",
    out = "module_doc.md",
    input = ":some_module.bzl",
)

Expected error;

 name 'tag_class' is not defined
 name 'module_extension' is not defined

EDIT: This is my .bazelrc, in case you find it useful.

common --experimental_enable_bzlmod
tetromino commented 2 years ago

I suspect this is related to https://github.com/bazelbuild/stardoc/issues/117 and https://github.com/bazelbuild/bazel/issues/14140.

nathaniel-brough commented 2 years ago

I don't know enough about #117 to rule it out, but I have a feeling it's unrelated. It seems to be that 'tag_class' and 'module_extension' are new native starlark symbols that are simply not handled with the stardoc parser.

I've got a more complete, traceback now for a different project bazelembedded/rules_cipd. 

bazel build //docs:module_doc --config bzlmod --verbose_failures 
INFO: Invocation ID: ff2f1796-3f77-43e1-80bf-8df99123d732
INFO: Analyzed target //docs:module_doc (0 packages loaded, 0 targets configured).
INFO: Found 1 target...
ERROR: /home/nathaniel/projects/rules_cipd/docs/BUILD.bazel:17:8: Generating proto for Starlark doc for module_doc failed: (Exit 1): stardoc failed: error executing command 
  (cd /home/nathaniel/.cache/bazel/_bazel_nathaniel/6015e436deec82624ded03e89dfa4d69/sandbox/linux-sandbox/12/execroot/rules_cipd && \
  exec env - \
  bazel-out/host/bin/external/stardoc.0.5.0/stardoc/stardoc '--input=//cipd:modules.bzl' '--workspace_name=rules_cipd' '--dep_roots=.' '--dep_roots=external/rules_cipd' '--output=bazel-out/k8-fastbuild/bin/docs/module_doc.raw')
# Configuration: 28ff57593ba01d914893f9cd455c859110ce813ccf3771961541220915f453dc
# Execution platform: @local_config_platform//:host

Use --sandbox_debug to see verbose messages from the sandbox
./cipd/internal/cipd_modules.bzl:20:20: name 'tag_class' is not defined
./cipd/internal/cipd_modules.bzl:26:8: name 'module_extension' is not defined
com.google.devtools.build.skydoc.SkydocMain$StarlarkEvaluationException: name 'tag_class' is not defined (+ 1 more)
        at com.google.devtools.build.skydoc.SkydocMain.recursiveEval(SkydocMain.java:393)
        at com.google.devtools.build.skydoc.SkydocMain.recursiveEval(SkydocMain.java:402)
        at com.google.devtools.build.skydoc.SkydocMain.eval(SkydocMain.java:260)
        at com.google.devtools.build.skydoc.SkydocMain.main(SkydocMain.java:163)
Stardoc documentation generation failed: name 'tag_class' is not defined (+ 1 more)
Target //docs:module_doc failed to build
chrislovecnm commented 1 year ago

Any updates on this? I know that @fmeum has done a bunch of work on bzlmod support. I am guessing that stardoc is now buildable using bzlmod but not supporting documenting extensions.

FWIW, I'm getting when I use stardoc 0.5.6

$ bazel run //docs:update
INFO: Analyzed target //docs:update (1 packages loaded, 18 targets configured).
INFO: Found 1 target...
ERROR: /home/clove/Workspace/src/github.com/bazelbuild/rules_python/docs/BUILD.bazel:97:8: Generating proto for Starlark doc for bzlmod-pip-docs failed: (Exit 1): bzlmod-pip-docs_stardoc failed: error executing command (from target //docs:bzlmod-pip-docs) bazel-out/k8-opt-exec-2B5CBBC6/bin/docs/bzlmod-pip-docs_stardoc '--input=@//python/extensions:pip.bzl' '--workspace_name=rules_python' '--output=bazel-out/k8-fastbuild/bin/docs/bzlmod-pip-docs.raw'

Use --sandbox_debug to see verbose messages from the sandbox and retain the sandbox build root for debugging
Exception in thread "main" net.starlark.java.eval.Starlark$UncheckedEvalException: InvalidStarlarkValueException thrown during Starlark evaluation
        at <starlark>.module_extension(<builtin>:0)
        at <starlark>.<toplevel>(/home/clove/.cache/bazel/_bazel_clove/a846dec765b6aaa49f6a6413a3f90026/sandbox/linux-sandbox/26/execroot/rules_python/bazel-out/k8-opt-exec-2B5CBBC6/bin/docs/bzlmod-pip-docs_stardoc.runfiles/rules_python/python/extensions/pip.bzl:76)
Caused by: net.starlark.java.eval.Starlark$InvalidStarlarkValueException: invalid Starlark value: class java.lang.Object
        at net.starlark.java.eval.Starlark.fromJava(Starlark.java:214)
        at net.starlark.java.eval.MethodDescriptor.call(MethodDescriptor.java:216)
        at net.starlark.java.eval.BuiltinFunction.fastcall(BuiltinFunction.java:77)
        at net.starlark.java.eval.Starlark.fastcall(Starlark.java:695)
        at net.starlark.java.eval.Eval.evalCall(Eval.java:682)
        at net.starlark.java.eval.Eval.eval(Eval.java:497)
        at net.starlark.java.eval.Eval.execAssignment(Eval.java:109)
        at net.starlark.java.eval.Eval.exec(Eval.java:268)
        at net.starlark.java.eval.Eval.execStatements(Eval.java:82)
        at net.starlark.java.eval.Eval.execFunctionBody(Eval.java:66)
        at net.starlark.java.eval.StarlarkFunction.fastcall(StarlarkFunction.java:174)
        at net.starlark.java.eval.Starlark.fastcall(Starlark.java:695)
        at net.starlark.java.eval.Starlark.execFileProgram(Starlark.java:985)
        at com.google.devtools.build.skydoc.SkydocMain.recursiveEval(SkydocMain.java:476)
        at com.google.devtools.build.skydoc.SkydocMain.eval(SkydocMain.java:289)
        at com.google.devtools.build.skydoc.SkydocMain.main(SkydocMain.java:151)

The extension is here:

https://github.com/bazelbuild/rules_python/blob/3903d1a5b94cf5908cdd571d5c09bb27a5310ce2/python/extensions/pip.bzl#L76

And I added:

stardoc(
    name = "bzlmod-pip-docs",
    out = "bzlmod-pip.md_",
    input = "//python/extensions:pip.bzl",
    target_compatible_with = _NOT_WINDOWS,
    deps = [
        ":bazel_repo_tools",
        ":pip_install_bzl",
        "@bazel_skylib//lib:versions",
    ],
)
tetromino commented 1 year ago

@silvergasp, as of https://github.com/bazelbuild/bazel/commit/fa6578261dabd3973cb9db2c72c99a9075fe84f8 we have a native rule in Bazel (starlark_doc_extract) to extract docs from Starlark in proto form.

This rule (unlike current Stardoc releases) at least does not crash on Starlark files containing module extensions - but it cannot document module extension objects (because we don't yet have representation for them in the proto). So in the case of the .bzl file given as example in https://github.com/bazelbuild/stardoc/issues/123#issue-1131472218, you will get docs for foo_impl, but not for foo itself.

The remaining steps would be approximately as follows: