stardoc fails to generate documentation for module extensions

[nathaniel-brough]

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]

I suspect this is related to #117 and bazelbuild/bazel#14140.

[nathaniel-brough]

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]

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]

@silvergasp, as of bazelbuild/bazel@fa65782 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 #123 (comment), you will get docs for foo_impl, but not for foo itself.

The remaining steps would be approximately as follows:

• update the proto format to describe module extension objects, and update native extractor to emit documentation for them
• fix the markdown renderer to work with the proto exported by the native extractor
• switch the Starlark rule to use the new native rule for doc extraction (exists in a branch, needs to be cleaned up and merged into master)