bazelbuild / stardoc

Stardoc: Starlark Documentation Generator

Stardoc - Starlark Documentation Generator

Stardoc is a documentation generator for Bazel build rules written in Starlark.

Stardoc provides a Starlark rule (stardoc, see documentation) that can be used to build documentation for Starlark rules in Markdown. Stardoc generates one documentation page per .bzlfile.

Get Started

• How to set up Stardoc for your project
• Writing docstrings
• How to integrate Stardoc with your build.
• See also Advanced Topics.

About Stardoc

• Stardoc rule reference.
• How to contribute to Stardoc

Project Status

Skydoc deprecation

Stardoc is a replacement for the deprecated "Skydoc" documentation generator.

See Skydoc Deprecation for details on the deprecation and migration details.

Future plans

See our future plans for refactoring Stardoc to be more consistent with how Bazel evaluates .bzl files, and what it means for maintenance of this project.

Maintainer's guide

See the maintaner's guide for instructions for cutting a new release.

stardoc's Issues

macro documentation has extra indent

python docstrings have to indent paragraphs under a parameter, for example for TypeScript we have this Args: section

https://github.com/bazelbuild/rules_nodejs/blob/ad0e2a4db40f0214ca6fc670d165c15c18de64ee/packages/typescript/internal/ts_project.bzl#L374-L419

The indent underneath each attribute is required to make the docstring syntax comply with the standard and for tools to parse it. In particular we have that line EXPERIMENTAL: generated tsconfig which is not documenting a parameter, it's just some more text in the documentation for tsconfig

When Stardoc produces the protobuf of the docstring the extra indent is still in there.

Note that it works out okay when you render the result in a place that isn't whitespace-sensitive, like in an HTML table. However if you render it in markdown you get a codeblock for each paragraph since leading indent is a markdown syntax for code block.

I think stardoc should de-dent this to canonicalize the doc back to what the author intended, by removing the four spaces from each line after the first in the docstring. so for my tsconfig attribute the proto's docString should be

Label of the tsconfig.json file to use for the compilation
To support "chaining" of more than one extended config, this label could be a target that
provdes <code>TsConfigInfo</code> such as <code>ts_config</code>.

By default, we assume the tsconfig file is named by adding <code>.json</code> to the <code>name</code> attribute.

EXPERIMENTAL: generated tsconfig

Instead of a label, you can pass a dictionary of tsconfig keys.

In this case, a tsconfig.json file will be generated for this compilation, in the following way:
- all top-level keys will be copied by converting the dict to json.
    So <code>tsconfig = {"compilerOptions": {"declaration": True}}</code>
    will result in a generated <code>tsconfig.json</code> with <code>{"compilerOptions": {"declaration": true}}</code>
- each file in srcs will be converted to a relative path in the <code>files</code> section.
- the <code>extends</code> attribute will be converted to a relative path

Note that you can mix and match attributes and compilerOptions properties, so these are equivalent:
...

Migrate stardoc source code from bazelbuild/bazel

I was trying to see what it would take to implement #27 but cannot find the source code. I'm assuming it's buried somewhere in bazelbuild/bazel. If this is the case, is there another issue tracking splitting that source code out into this repo? Also, if this is true, would it also be possible to update the CONTRIBUTING.md doc to call this out?

Crash when macro param default value is a `select()`

Description of the problem:

I tried to use Stardoc to generate som documents and then I ran into a problem when select() was used. I got the following error:

Exception in thread "main" java.util.UnknownFormatConversionException: Conversion = 'cannot use %r substitution placeholder when simplifiedFormatStrings is set'

Bugs: what's the simplest, easiest way to reproduce this bug? Please provide a minimal example if possible.

To show some more simple example I just made a very small update into the Bazel C++ tutorial and I got the same error.
I added .bazelrc in stage2 directory and a new file hello-world.bzl in the main sub-directory and updated the BUILD file in the same sub-directory.

.../examples/cpp-tutorial/stage2 -> 
README.md
WORKSPACE
lib
main
.bazelrc

.../examples/cpp-tutorial/stage2/main -> 
BUILD
hello-greet.cc
hello-greet.h
hello-time.cc
hello-time.h
hello-world.bzl

In the .bazelrc file I added the following:

build:apple  --fruit=apple
build:orange  --fruit=orange
build:banana  --fruit=banana

And the hello-world.bzl have the following content:

DEFAULT_FRUIT_CONFIG = (select({
    "apple": "red",
    "banana": "yellow",
    "orange": "orange",
}))

def fruit_colour_with_select(fruit_colour = DEFAULT_FRUIT_CONFIG):
    """
    **fruit_colour_with_select** finds out colour of the fruit.
    """
    return(fruit_colour)

def fruit_colour_no_select(fruit_colour = "blue"):
    """
    **fruit_colour_no_select** returns fruit colour blue.
    """
    return(fruit_colour)

I added the following into the BUILD file:

load(
    "@io_bazel_stardoc//stardoc:stardoc.bzl",
    "stardoc"
)
load(
    "@bazel_skylib//:bzl_library.bzl",
    "bzl_library"
)

config_setting(
    name = "apple",
    values = {"fruit": "apple"},
)

config_setting(
    name = "banana",
    values = {"fruit": "banana"},
)

config_setting(
    name = "orange",
    values = {"fruit": "orange"},
)

stardoc(
    name = "hello-world-docs-no-select",
    input = "hello-world.bzl",
    out = "hello_world_doc_no_select.md",
    symbol_names = [
        "fruit_colour_no_select",]
)
stardoc(
    name = "hello-world-docs-with-select",
    input = "hello-world.bzl",
    out = "hello_world_doc_with_select.md",
    symbol_names = [
        "fruit_colour_with_select",]
)

It works to generate document for target hello-world-docs-no-select but not for hello-world-docs-with-select:

OK:
bazel build //main:hello-world-docs-no-select 
NOK:
bazel build //main:hello-world-docs-with-select 
bazel build //main:hello-world-docs-with-select  --define="fruit=apple"

.../examples/cpp-tutorial/stage2 -> bazel build //main:hello-world-docs-no-select 
INFO: Invocation ID: ba902970-4211-47e8-87cd-c5939095e0f9
INFO: Analyzed target //main:hello-world-docs-no-select (0 packages loaded, 1 target configured).
INFO: Found 1 target...
Target //main:hello-world-docs-no-select up-to-date:
  bazel-bin/main/hello_world_doc_no_select.md
INFO: Elapsed time: 0.131s, Critical Path: 0.01s
INFO: 0 processes.
INFO: Build completed successfully, 1 total action

.../examples/cpp-tutorial/stage2 -> bazel build //main:hello-world-docs-with-select 
INFO: Invocation ID: e369f3cb-685b-4954-b6d6-a84ba5e59404
INFO: Analyzed target //main:hello-world-docs-with-select (0 packages loaded, 0 targets configured).
INFO: Found 1 target...
ERROR: /repo/.../examples/cpp-tutorial/stage2/main/BUILD:47:1: Generating proto for Starlark doc for hello-world-docs-with-select failed (Exit 1) stardoc failed: error executing command 
  (cd /repo/$USER/bazel_build_root/testbaselib/sandbox/processwrapper-sandbox/6/execroot/__main__ && \
  exec env - \
  bazel-out/host/bin/external/io_bazel_stardoc/stardoc/stardoc '--input=//main:hello-world.bzl' '--workspace_name=' '--symbols=fruit_colour_with_select' '--dep_roots=.' '--dep_roots=external/' '--output=bazel-out/k8-fastbuild/bin/main/hello-world-docs-with-select.raw')
Execution platform: @bazel_tools//platforms:host_platform

Use --sandbox_debug to see verbose messages from the sandbox
Exception in thread "main" java.util.UnknownFormatConversionException: Conversion = 'cannot use %r substitution placeholder when simplifiedFormatStrings is set'
	at com.google.devtools.build.lib.syntax.Printer$BasePrinter.formatWithList(Printer.java:495)
	at com.google.devtools.build.lib.syntax.Printer$BasePrinter.format(Printer.java:453)
	at com.google.devtools.build.lib.syntax.Printer$BasePrinter.format(Printer.java:188)
	at com.google.devtools.build.lib.syntax.SelectorValue.repr(SelectorValue.java:81)
	at com.google.devtools.build.lib.syntax.Printer$BasePrinter.repr(Printer.java:279)
	at com.google.devtools.build.lib.syntax.Printer$BasePrinter.appendListElements(Printer.java:405)
	at com.google.devtools.build.lib.syntax.Printer$BasePrinter.printList(Printer.java:387)
	at com.google.devtools.build.lib.syntax.Printer$BasePrinter.printList(Printer.java:188)
	at com.google.devtools.build.lib.syntax.SelectorList.repr(SelectorList.java:172)
	at com.google.devtools.build.lib.syntax.Printer$BasePrinter.repr(Printer.java:279)
	at com.google.devtools.build.skydoc.rendering.FunctionUtil.forParam(FunctionUtil.java:89)
	at com.google.devtools.build.skydoc.rendering.FunctionUtil.parameterInfos(FunctionUtil.java:138)
	at com.google.devtools.build.skydoc.rendering.FunctionUtil.fromNameAndFunction(FunctionUtil.java:72)
	at com.google.devtools.build.skydoc.rendering.ProtoRenderer.appendStarlarkFunctionInfos(ProtoRenderer.java:58)
	at com.google.devtools.build.skydoc.SkydocMain.main(SkydocMain.java:254)
Target //main:hello-world-docs-with-select failed to build
INFO: Elapsed time: 0.688s, Critical Path: 0.59s
INFO: 0 processes.
FAILED: Build did NOT complete successfully

.../examples/cpp-tutorial/stage2 -> bazel build //main:hello-world-docs-with-select  --define="fruit=apple"
INFO: Invocation ID: aee445cf-6787-4f08-9b6c-6a8a28cea73b
INFO: Build option --define has changed, discarding analysis cache.
INFO: Analyzed target //main:hello-world-docs-with-select (0 packages loaded, 259 targets configured).
INFO: Found 1 target...
ERROR: /repo/.../examples/cpp-tutorial/stage2/main/BUILD:47:1: Generating proto for Starlark doc for hello-world-docs-with-select failed (Exit 1) stardoc failed: error executing command 
  (cd /repo/uabelma/bazel_build_root/testbaselib/sandbox/processwrapper-sandbox/7/execroot/__main__ && \
  exec env - \
  bazel-out/host/bin/external/io_bazel_stardoc/stardoc/stardoc '--input=//main:hello-world.bzl' '--workspace_name=' '--symbols=fruit_colour_with_select' '--dep_roots=.' '--dep_roots=external/' '--output=bazel-out/k8-fastbuild/bin/main/hello-world-docs-with-select.raw')
Execution platform: @bazel_tools//platforms:host_platform

Use --sandbox_debug to see verbose messages from the sandbox
Exception in thread "main" java.util.UnknownFormatConversionException: Conversion = 'cannot use %r substitution placeholder when simplifiedFormatStrings is set'
	at com.google.devtools.build.lib.syntax.Printer$BasePrinter.formatWithList(Printer.java:495)
	at com.google.devtools.build.lib.syntax.Printer$BasePrinter.format(Printer.java:453)
	at com.google.devtools.build.lib.syntax.Printer$BasePrinter.format(Printer.java:188)
	at com.google.devtools.build.lib.syntax.SelectorValue.repr(SelectorValue.java:81)
	at com.google.devtools.build.lib.syntax.Printer$BasePrinter.repr(Printer.java:279)
	at com.google.devtools.build.lib.syntax.Printer$BasePrinter.appendListElements(Printer.java:405)
	at com.google.devtools.build.lib.syntax.Printer$BasePrinter.printList(Printer.java:387)
	at com.google.devtools.build.lib.syntax.Printer$BasePrinter.printList(Printer.java:188)
	at com.google.devtools.build.lib.syntax.SelectorList.repr(SelectorList.java:172)
	at com.google.devtools.build.lib.syntax.Printer$BasePrinter.repr(Printer.java:279)
	at com.google.devtools.build.skydoc.rendering.FunctionUtil.forParam(FunctionUtil.java:89)
	at com.google.devtools.build.skydoc.rendering.FunctionUtil.parameterInfos(FunctionUtil.java:138)
	at com.google.devtools.build.skydoc.rendering.FunctionUtil.fromNameAndFunction(FunctionUtil.java:72)
	at com.google.devtools.build.skydoc.rendering.ProtoRenderer.appendStarlarkFunctionInfos(ProtoRenderer.java:58)
	at com.google.devtools.build.skydoc.SkydocMain.main(SkydocMain.java:254)
Target //main:hello-world-docs-with-select failed to build
INFO: Elapsed time: 0.815s, Critical Path: 0.59s
INFO: 0 processes.
FAILED: Build did NOT complete successfully
seroiuvd05211:.../examples/cpp-tutorial/stage2 -> 

What operating system are you running Bazel on?

Linux

What's the output of bazel info release?

0.28.1
Now we have 3.3.1 and it's still the same problem

Have you found anything relevant by searching the web?

No

Stardoc should support linking to other symbols

... a la javadoc's {@link ...} construct. The syntax of the link should not depend on the output format (<a></a> vs [...](...)), and should not require embedding any URLs but rather directly use names of imported symbols.

(Unimported symbols might be referenced via the .bzl label that would've been used had they been imported, so you don't have to load things just for the sake of documentation completeness. But I'm not sure how that interacts with searching for transitive dependencies, bzl_library, etc.)

Change release structure

When fetching sratdoc release there is additional stardoc-0.4.0 folder created inside of it. As a result, when fetching files using http_archive rule you can't reference code by just using startdoc, you need to include version number as well.
Example:

1. When fetching via git_repository rule you can use following: load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
2. When fetching via http_archive you must use following: load("@bazel_stardoc//stardoc-0.4.0/stardoc:stardoc.bzl", "stardoc")
   I was using files provided on https://github.com/bazelbuild/stardoc/releases/tag/0.4.0

In general, Bazel recommends using http_archive rules instead of git_repository rules (see here). Maybe you can update the instructions in getting_started_stardoc.md as well.

Autodocument enumerated "values" of rule/aspect attributes

Consider the following rule attribute definition:

"format": attr.string(
    doc = "The format of the output file.",
    default = "markdown",
    values = ["markdown", "proto"],
),

It would be best if Stardoc documented the available values for "format" automatically.

stardoc NoSuchFileException when the `input` not the same as rule `name`

I had cause to write a rule that generated a .bzl file and then pass that to the stardoc function as an input.
The problem was that the file that stardoc then looks for is the name of the rule and NOT the name of the file passed in.

For example:

Here is my rule:

def _stub_impl(ctx):
    methods_str = "\n"
    for m in ctx.attr.methods:
      methods_str += "def %s:\n  pass\n" % m

    grep_strings = []
    for m in ctx.attr.methods:
      grep_strings.append("grep -v \"\\\"%s\\\"\"" % m)
    grep_string = " | ".join(grep_strings)

    # we append a series of mock methods to the end of the file
    ctx.actions.run_shell(
        inputs = [ctx.file.input],
        outputs = [ctx.outputs.output],
        command = "echo '%s' | cat %s - | %s > %s" % (methods_str, ctx.file.input.path, grep_string, ctx.outputs.output.path),
    )

stub = rule(
    implementation = _stub_impl,
    attrs = {
        "input": attr.label(allow_single_file = True),
        "methods": attr.string_list(),
    },
    outputs = {
        "output": "%{name}.bzl",
    },
)

This will stub out the methods from a .bzl file that depend on external libraries that dont play well with stardoc (rules_go) for example.

The BUILD file then looked like:

stub(
	name = "stub",
	input = "file.bzl",
	methods = ["go_binary"]
)
stardoc(
    name = "docs",
    input = ":stub.bzl",
    out = "doc.md",
)

This will not work because the argument passed to the StarDoc java bin is '--input=//tools/go:stub' and not '--input=//tools/go:stub.bzl' so it causes a

Exception in thread "main" java.nio.file.NoSuchFileException: tools/go/stub
	at com.google.devtools.build.skydoc.SkydocMain.getInputSource(SkydocMain.java:490)

The solution to this is to remove the .bzl from output, e.g. "output": "%{name}", and change the name of the rule to be stub.bzl, this raises a warning in Bazel (so not great).

The goal here is to either:

1. Allow for better handling of third_party bzl files in stardoc, so I wont need to stub
2. use the actual ctx.file.input.path as input to the docs and stop guessing the location using dep_roots
3. Allow a rule of a different name as input and still find file.

Cheers

cross-repository references broken in Bazel 2.0

Noted here:

bazelbuild/bazel#10131 (comment)

the pattern of handling cross-repository references which was introduced for rules_rust (and I then borrowed in rules_nodejs) is broken by the next upcoming Bazel release

Take down skydoc.bazel.build

The getting started page recommends a WORKSPACE incantation that is no longer needed for Stardoc.

@aiuto

Change test golden files to use .md suffix instead of .txt

This makes it trivial to inspect the github-rendering of these goldens in a github pull request

Support documenting Skylark Aspects

Tracking bug for implementing support for documenting Aspects.

Documentation from hidden rule attributes in public macro

Say there's a .bzl file similar to the following

_my_rule = rule(
    implementation = _my_rule_impl,
    doc = "my special rule",
    attrs = {
        "a": attr.string(
            doc = "Documentation for 'a'",
        ),
        "b": attr.string(
            doc = "Documentation for 'b'",
        ),
    }
)

def my_rule(name, **kwargs):
    """My special rule wrapper
    
    Args:
        name: name of the rule
        **kwargs: _my_rule attributes

    Returns:
        The name of the rule
    """

    _my_rule(
        name = "my_" + name,
        **kwargs,
    )

    return "my_" + name

Is it possible to generate docs for _my_rule's attributes without making it public?

Generated markdown pages don't have a title

It looks like the markdown pages never get a page title (# TITLE line), so the documented symbol gets a heading marking (## SYMBOL_NAME), and thus becomes the page title. So when the page has a few symbols things are a little odd when rendered by most markdown engines.

I'm not sure if #25 would be the way to fix this or if the intent is for everyone to use a custom template for every generated page.

deps in bzl_library() incorrect handled in stardoc()

We have a structure similar to this:

[workspace]/
    WORKSPACE
    BUILD
    macro/
        BUILD
        macro.bzl
    docs/
        BUILD

The macro.bzl use string_flag() and therefore have this load statement.

load(
    "@bazel_skylib//rules:common_settings.bzl",
    "string_flag",
)

To be able to generate documentation for the macros in macro.bzl
we must take care of the dependency so we have made 2 bzl_library() targets in macro/BUILD:

load("@bazel_skylib//:bzl_library.bzl", "bzl_library")

bzl_library(
    name = "macro-deps",
    srcs = [
        "@bazel_skylib//rules:common_settings.bzl",
    ],
    visibility = ["//visibility:public"],
)

bzl_library(
    name = "macro-code",
    srcs = [
        "macro.bzl",
    ],
    visibility = ["//visibility:public"],
)

In BUILD below docs we have gathered all stardoc() rules.
For the macro above we have the following rule:

load("@bazel_stardoc//stardoc:stardoc.bzl", "stardoc")

stardoc(
    name = "config-bool-docs",
    out = "config-bool.md",
    input = "//macro:macro-code",
    symbol_names = ["config_option_bool"],
    deps = ["//macro:macro-deps"],
)

This works BUT what we actually would like to have is this:
macro/BUILD:

load("@bazel_skylib//:bzl_library.bzl", "bzl_library")

bzl_library(
    name = "macro-deps",
    srcs = [
        "@bazel_skylib//rules:common_settings.bzl",
    ],
)

bzl_library(
    name = "macro-code",
    srcs = [
        "macro.bzl",
    ],
    deps= [
        "macro-deps",
    ],
    visibility = ["//visibility:public"],
)

And in docs/BUILD:

load("@bazel_stardoc//stardoc:stardoc.bzl", "stardoc")

stardoc(
    name = "config-bool-docs",
    out = "config-bool.md",
    input = "//macro:macro-code",
    symbol_names = ["config_option_bool"],
)

So that we have the deps in macro-code target instead of the stardoc() target.
Shouldn't that work?
It doesn't build but I think that it should and that this is a bug.
It doesn't follow the usual Bazel way of treating the dependencies

As stated above in docs/BUILD we have gathered all stardoc() rules (also for more than the above docs/macro ) .
We think that all dependencies should be stated in BUILD's where we have the code and those BUILD's shall provide the public bzl_library() targets that can be used in the stardoc() rules in docs/BUILD. The targets below docs should not need to keep track of the dependencies.

Stardoc doesn't work with Bazel head

Test setup:

cd
git clone https://github.com/bazelbuild/stardoc
git clone https://github.com/bazelbuild/bazel
cat <<EOF > stardoc/.bazelrc
common --override_repository=io_bazel=${HOME}/bazel
EOF

Configure the bisect to run between HEAD and b2b9fa00d7d168e9553cfc9fe381928e8e246176 (which is currently in the workspace and I checked worked).

git bisect start
git bisect bad HEAD
git bisect good b2b9fa00d7d168e9553cfc9fe381928e8e246176

Now run the bisect:

git bisect run bash -c '(set -e && cd ~/stardoc && ./update-release-binary.sh)'

This appears to be the bad commit.

54491ef4e4be8d09f4473141212c148fa0bffb2b is the first bad commit
commit 54491ef4e4be8d09f4473141212c148fa0bffb2b
Author: ahumesky <[email protected]>
Date:   Thu Jul 30 16:57:33 2020 -0700

    Add AndroidSdkInfo to Bazel behind --experimental_google_legacy_api

    RELNOTES: None.
    PiperOrigin-RevId: 324113180

 .../devtools/build/docgen/SymbolFamilies.java      |   4 +-
 .../lib/bazel/rules/BazelRuleClassProvider.java    |   4 +-
 .../starlarkbuildapi/android/AndroidBootstrap.java |   9 +-
 .../google/devtools/build/skydoc/SkydocMain.java   |   6 +-
 .../build/skydoc/fakebuildapi/android/BUILD        |   3 +
 .../android/FakeAndroidSdkProvider.java            | 159 +++++++++++++++++++++
 6 files changed, 179 insertions(+), 6 deletions(-)
 create mode 100644 src/main/java/com/google/devtools/build/skydoc/fakebuildapi/android/FakeAndroidSdkProvider.java
bisect run success

and the build error is:

ERROR: <snip>/external/io_bazel/src/main/java/com/google/devtools/build/lib/exec/BUILD:243:13: no such package '@remoteapis//': The repository '@remoteapis' could not be resolved and referenced by '@io_bazel//src/main/java/com/google/devtools/build/lib/exec:spawn_log_context'
ERROR: Analysis of target '@io_bazel//src/main/java/com/google/devtools/build/skydoc:skydoc_deploy.jar' failed; build aborted: Analysis failed

Unfortunately, from looking at the diff I can't tell why this CL would be an issue. Do you have any ideas? Why @remoteapis?

README.md improvements

We need documentation for:

1. Release / rollout process documentation
2. Docstring formatting
3. Use of custom templates / other template schemes, including how to create vm templates and use util libraries
4. Proto output format

Documentation Inheritance

As explained in bazelbuild/bazel#7977, there's a common use case for macros which serve as thin wrappers on rule invocations. In such cases, it's inconvenient and maintenance-heavy to manually mirror rule documentation as macro documentation:

def _rule_impl(ctx):
    bin_output = ctx.outputs.bin_output
    ...
    return [OutputGroupInfo(bin = depset([bin_output])]

_my_rule = rule(
    implementation = _my_rule_impl,
    doc = "My rule is the best rule",
    attrs = {
       "bin_output" : attr.output(doc = "Binary output"),
       "foo" : attr.string(doc = "Lorem ipsum dolor sit amet")
    }
)

def my_rule(name, **kwargs):
    """My rule is the best rule.

    Args:
      name: The name of the test rule.
      foo: Lorem ipsum dolor sit amet
      bin_output: Binary output. `name` + '.exe' by default.
      **kwargs: Other attributes to include
    """
    
    _my_rule(name = name,
        bin_output = name + ".exe",
        **kwargs)

There are several issues here:

• Duplication between the root and argument documentation in the my_rule macro and the _my_rule rule
• The Args section of the macro does not appropriately match the rule. There is no "foo" parameter of the macro, but it might be part of kwargs.
• We need not document kwargs, as all kwargs should also be documented in _my_rule

I propose a macro metatag (for Stardoc to recognize) which effectively notes inheritance of documentation. So instead:

def my_rule(name, **kwargs):
    """@inherit(_my_rule)

   Args:
     bin_output: `name` + '.exe' by default.
    """
    
    _my_rule(name = name,
        bin_output = name + ".exe",
        **kwargs)

Note this new format will also need to be recognized by buildifier, so that buildifier does not emit warnings even if the Args section of the macro's docstring does not match the arguments of the macro. (Related to bazelbuild/buildtools#649)

Add a page layout template with parsed directives in comments

The Asylo project is interested in producing its .bzl file documentation with stardoc. Currently it is hand-written and therefore out of date

We want to be able to drive more of the page layout ourselves. Right now there are templates for the individual types of Starlark constructs, but here is no template for the overall page layout.
The layout in stardoc is alphabetical order only, with no user-provided header, footer, or ability to add descriptive interludes. This makes documentation of concepts that are shared amongst documented constructs hard.

What I'd like to see is a page template that can reference variables that are declared in parsed comments, and metadata attached to various documentable constructs.

Say we have a .bzl file:

# stardoc:block{my_variable}
# content
# more content

def macro1(arg):
  """Documentation"""
  stuff()

# stardoc:let{other_variable}{4}
# stardoc:meta:group{top_group}
a = rule(implementation = _impl; attrs = {...})

The tag stardoc:block binds the content of the rest of the comment to the declared variable. That variable can be referenced in the page template for the stardoc target. This could be in a docInfo object as either a field (docInfo.my_variable) or as a map lookup (docInfo.var["my_variable"]); I don't particularly care, so whichever is easier.

Then we have a page.vm template file:

---
${docInfo.my_variable}
---

#foreach ($construct in $docInfo.getSortedConstructsByGroup("top_group"))
${construct.render()}
#end

#foreach ($construct in $docInfo.getSortedConstructs())
#if (!$construct.in_group("top_group"))
${construct.render()}
#end
#end

I'm sure metadata is a whole different thing than just binding variables to values. So I'm okay with this feature request getting split into the page template with simple variables and page template with attached-metadata separate feature requests.

Right now, the Asylo project does post-processing on the md files we generate given the supposed source .bzl file, and tosses in a header that's defined by a specially-tagged comment block. We'd really like to better group our documented constructs to talk about rules here, providers there, or "this bunch of conceptually similar things" and that. An added bonus with using templates and stardoc is that unbound variables could cause warnings, and we could catch missing Jekyll metadata (in the ---/--- block).

`symbol_names` is documented in a few places as only defaulting to `rule` entries

https://github.com/bazelbuild/stardoc/blob/master/docs/stardoc_rule.md#stardoc-symbol_names

https://github.com/bazelbuild/stardoc/blob/master/docs/generating_stardoc.md#single-file

Seem to say if nothing is provide for symbol_names, it defaults to only documenting the rule entries.

But https://github.com/bazelbuild/stardoc/blob/master/docs/writing_stardoc.md does say:

Stardoc will, by default, generate documentation for all rules, macros, and functions reachable from a target .bzl file.

But then links over to the other doc which just talks about rules again.

https://github.com/bazelbuild/stardoc/blob/master/docs/writing_stardoc.md#rule-documentation also mentioned that attributes with a leading underscore (_) won't be documented, but nothing indicates if the default behavior for symbol_names will do something similar (skipping runes, macros, or providers that start with a underscore).

Support for build settings documentation

Support for build settings that get defined in BUILD files? (somewhat like #22 & #31)

https://docs.bazel.build/versions/master/skylark/config.html#defining-build-settings

• build_setting

https://docs.bazel.build/versions/master/skylark/config.html#label-typed-build-settings

• label_flag
• label_setting

Stardoc crashes when interacting with `apple_common` global

When Stardoc encounters the following bit of code in rules_go,

_PLATFORMS = {
    "armv7-apple-ios": (apple_common.platform.ios_device, apple_common.platform_type.ios),
    "armv7-apple-tvos": (apple_common.platform.tvos_device, apple_common.platform_type.tvos),
    "armv7k-apple-watchos": (apple_common.platform.watchos_device, apple_common.platform_type.watchos),
    "arm64-apple-ios": (apple_common.platform.ios_device, apple_common.platform_type.ios),
    "arm64-apple-tvos": (apple_common.platform.tvos_device, apple_common.platform_type.tvos),
    "i386-apple-ios": (apple_common.platform.ios_simulator, apple_common.platform_type.ios),
    "i386-apple-tvos": (apple_common.platform.tvos_simulator, apple_common.platform_type.tvos),
    "i386-apple-watchos": (apple_common.platform.watchos_simulator, apple_common.platform_type.watchos),
    "x86_64-apple-ios": (apple_common.platform.ios_simulator, apple_common.platform_type.ios),
    "x86_64-apple-tvos": (apple_common.platform.ios_simulator, apple_common.platform_type.tvos),
    "x86_64-apple-watchos": (apple_common.platform.watchos_simulator, apple_common.platform_type.watchos),
}

it throws the following error:

SUBCOMMAND: # //go:def-docs [action 'Generating proto for Starlark doc for def-docs', configuration: faff19e6fd939f490ac11578d94024c6b7a032836cde039fd5edd28b838194e8, execution platform: @local_config_platform//:host]
(cd <snip> && \
  exec env - \
  bazel-out/host/bin/external/io_bazel_stardoc/stardoc/stardoc '--input=//go:def.bzl' '--workspace_name=io_bazel_rules_go' '--dep_roots=.' '--dep_roots=external/io_bazel_rules_go' '--output=bazel-out/k8-fastbuild/bin/go/def-docs.raw')
ERROR: <snip>/rules_go/go/BUILD.bazel:61:8: Generating proto for Starlark doc for def-docs failed (Exit 1) stardoc failed: error executing command bazel-out/host/bin/external/io_bazel_stardoc/stardoc/stardoc '--input=//go:def.bzl' '--workspace_name=io_bazel_rules_go' '--dep_roots=.' '--dep_roots=external/io_bazel_rules_go' ... (remaining 1 argument(s) skipped)

Use --sandbox_debug to see verbose messages from the sandbox
com.google.devtools.build.skydoc.SkydocMain$StarlarkEvaluationException: Starlark evaluation error
        at com.google.devtools.build.skydoc.SkydocMain.recursiveEval(SkydocMain.java:423)
        at com.google.devtools.build.skydoc.SkydocMain.recursiveEval(SkydocMain.java:397)
        at com.google.devtools.build.skydoc.SkydocMain.recursiveEval(SkydocMain.java:397)
        at com.google.devtools.build.skydoc.SkydocMain.eval(SkydocMain.java:255)
        at com.google.devtools.build.skydoc.SkydocMain.main(SkydocMain.java:158)
Caused by: Traceback (most recent call last):
        File "./go/platform/apple.bzl", line 16, column 46, in <toplevel>
                "armv7-apple-ios": (apple_common.platform.ios_device, apple_common.platform_type.ios),
Error:
        at net.starlark.java.eval.Starlark.errorf(Starlark.java:555)
        at net.starlark.java.eval.Starlark.getattr(Starlark.java:606)
        at net.starlark.java.eval.Eval.evalDot(Eval.java:530)
        at net.starlark.java.eval.Eval.eval(Eval.java:446)
        at net.starlark.java.eval.Eval.evalList(Eval.java:704)
        at net.starlark.java.eval.Eval.eval(Eval.java:466)
        at net.starlark.java.eval.Eval.evalDict(Eval.java:509)
        at net.starlark.java.eval.Eval.eval(Eval.java:444)
        at net.starlark.java.eval.Eval.execAssignment(Eval.java:108)
        at net.starlark.java.eval.Eval.exec(Eval.java:260)
        at net.starlark.java.eval.Eval.execStatements(Eval.java:80)
        at net.starlark.java.eval.Eval.execFunctionBody(Eval.java:64)
        at net.starlark.java.eval.StarlarkFunction.fastcall(StarlarkFunction.java:155)
        at net.starlark.java.eval.Starlark.fastcall(Starlark.java:509)
        at net.starlark.java.eval.Starlark.execFileProgram(Starlark.java:779)
        at com.google.devtools.build.skydoc.SkydocMain.recursiveEval(SkydocMain.java:420)
        ... 4 more

To view, clone, and test this change, please see my CL to be: https://github.com/achew22/rules_go/pull/new/stardoc
and bazel build //go:def-docs

Support getting a page preamble

Looks like the markdown generated starts out with a ## [NAME] for everything thing documented, but there doesn't seem to be a way to get any preamble on to the page, especially a # [TITLE] since that likely will be used by some system.

The easiest might be to just support a title on the rule to insert this vs. and then let something like bazelbuild/skydoc#159 end up providing any content after the title before the listing of symbols.

Example section no longer recognized in docstrings

Skydoc recognizes special sections in docstrings such as Args: and Example:. Stardoc still recognizes Args: but no longer recognizes Example:. Given the following docstring:

def some_function(name, arg):
    """This is some function.

    Example:
      Here is an example:

      ```bzl
      foo = some_function("name", "arg")
      ```

    Args:
      name: The name.
      arg: The argument.
    """

I would expect output containing markdown along the lines of

### Examples
Here is an example:
```bzl
foo = some_function("name", "arg")
```
### Attributes
...

However, Stardoc no longer generates a section (or a proto entry) for examples.

We have several such examples in the rules_haskell documentation (source, rendered).

A workaround is to use level 3 headings (###) in the docstring directly. However, this makes the Example and Args sections inconsistent in the source docstring.

I did not compare other special sections, e.g. Returns:. However, looking at the proto it seems that Args: is the only section that Stardoc recognizes.

How should users migrating from Skydoc to Stardoc handle such sections? Could support for further sections be added to Stardoc?

Stardoc cannot handle input files from remote repositories

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>

Stardoc code should not be intertwined in Bazel source tree

This might be blocked on pulling Starlark out of Bazel. It seems very wrong that the formatting code is in the Bazel source. See bazelbuild/bazel#9240 for reference

skydoc.bazel.build is out of date

The getting started page refers to skydoc 0.0.3: https://skydoc.bazel.build/docs/getting_started.html

Cut a release that includes support for keyword-only arguments

Bazel 2.1 instroduced Starlark changes that allow keyword-only parameters.

For example:

def foo(arg1, arg2, *, kwonly1):
    pass

But running Stardoc 0.4.0 on .bzl files with that new syntax fails with:

Stardoc documentation generation failed: Starlark evaluation error

Improve documentation for utility functions available to custom templates

Right now, the documentation links to a raw java file, which is intimidating. We should make it clear that users are encouraged to use the available utility functions, and we should make it more obvious what functions are available.

Support module docstrings

Code change made in bazelbuild/bazel@5faf952 to support adding module docstrings to Stardoc output. The templates still need to be updated to reflect this new feature.

Add types in the parameter table when generating function document with Stardoc

We are trying to use Stardoc when generating documentation for our Bazel macros. I can get a table generated with parameter descriptions when follow the instruction here: Macro/Function documentation

But we would also like to add the parameter Type in the table.
According to DocstringUtils.java it seems like we shall write the Type in parentheses after the parameter name but before colon, as this example:

another_parameter (unused, mutable): a parameter may be followed by additional attributes in parenthese

I have seen that it's possible to add a rule template to the stardoc() rule (attribute: func_template). I started to use an own copy of the default template to play around with: //stardoc:templates/markdown_tables/func.vm
If I have understood correctly it doesn't seem that the attributes that I add in paranthese is fetched. And I don't think that I will be able to retreive that information by just updating the template. So I think that it will need an update in the Stardoc code for this, correct?! Is that something that is already planned? If I'm not correct then I would appreciate information how I can retreive the value of the attribute.

Thanks!

Error generating function docs on windows, related to line endings

Error is

ERROR: D:/b/7cfqmzbl/external/npm_bazel_terser/BUILD.bazel:32:1: Couldn't build file external/npm_bazel_terser/docs.raw: Generating proto for Starlark doc for docs failed (Exit 1)
Exception in thread "main" com.google.devtools.build.skydoc.rendering.DocstringParseException: Unable to generate documentation for function node_repositories (defined at internal/node/node_repositories.bzl:688:5) due to malformed docstring. Parse errors:
  internal/node/node_repositories.bzl:688:5 line 2: the one-line summary should be followed by a blank line

	at com.google.devtools.build.skydoc.rendering.FunctionUtil.fromNameAndFunction(FunctionUtil.java:61)
	at com.google.devtools.build.skydoc.rendering.ProtoRenderer.appendStarlarkFunctionInfos(ProtoRenderer.java:58)

see bazelbuild/rules_nodejs@299d2b5 - can probably repro there

Support lists in Description column

We see needs for supporting bulleted or numbered lists format inside the Description cell in the table for our macro documents (would need an update of util.markdownCellFormat() function in Bazel which formats the cell so it's not possible to just update the template).
Sometimes we have a list och dictionaries or strings in the table (in one row) and need to have a description of each element inside one cell. It can be quite many elements so it gives quite much text and have needs to be structured in a way so the information will be clear. We also in the Description have a need to inform about default value of a specific dictionary/list (can't be informed in the Default column since that would be just [ ]). So all in all we think that lists would help us to structure the information so it gets more readable.

Extract documentation for named constants

Since feature flags are used by rules to enable behaviors (sanitizers, etc.), and they can be used globals with a bazel command line or via the common features rule attribute.

Generally, the features are just string values. Some projects use a constant in their bzl so they can ensure the same value is used in all cases the impls need it. That pattern generally works to provide a basis extracting the information into documentation. rules_swift is an example of this: https://github.com/bazelbuild/rules_swift/blob/master/swift/internal/features.bzl#L17-L115

So it would be nice if there was some way to scrap the string values and descriptions to make a page.

Convenience rule for verifying checked-in documentation matches Stardoc output

We could probably leverage Stardoc's existing test-verification rules and provide users some convenience rules to help in managing checked-in Stardoc output.

Change alignment of columns in table

Hi,

We want to have top aligned Name column in the table for our generated macro documents.
The reason for this is because sometimes we have quite much text in the Description column and then the Name is hard to see when it's aligned in the middle.

We have tried to keep the Markdown format in the template and achieve this but have failed with that.
Instead of:

| Name  | Description | Default Value |
| :------------- | :------------- | :------------- |
#foreach ($param in $funcInfo.getParameterList())
| <a id="${funcInfo.functionName}-${param.name}"></a>$param.name | #if(!$param.docString.isEmpty()) ${util.markdownCellFormat($param.docString)} #else <p align="center"> - </p> #end  | #if(!$param.getDefaultValue().isEmpty()) <code>$param.getDefaultValue()</code> #else none #end|
#end

We have now added html to be able to get the alignment:

<table>
<tr>
<th align="left">Name</th>
<th align="left">Description</th>
<th align="left">Mandatory</th>
<th align="left">Default Value</th>
</tr>
#foreach ($param in $funcInfo.getParameterList())
<tr>
 <td valign="top" align="left"><a id="${funcInfo.functionName}-${param.name}"></a>$param.name </td>
 <td align="left">

#if(!$param.docString.isEmpty()) ${util.markdownCellFormat($param.docString)}#else <p align="center"> - </p> #end

 </td>
 <td align="left"> $param.mandatory </td>
 <td align="left"> #if(!$param.getDefaultValue().isEmpty())<code>$param.getDefaultValue()</code> #else none #end </td>
</tr>
#end
</table>

It's not what we prefer since it will not be as nice to read as Markdown.

Do you have any idea how to fix this and still keep the Markdown format?

We can live with our html in the template but it's not the preferred solution.

Thanks!

Rule documentation documents for visible name, not exported name

If one does:

my_rule = rule(...)
foo_rule = my_rule

and then generates documentation for foo_rule, it may be confusing to users that invoking bazel query on targets of foo_rule actually show the rule of these targets as being my_rule.
We may want to consider automatically documenting the 'query-visible' name of a rule.

macros/functions don't support documenting a return result.

Not all macros are meant to appear like rules. Some can be building block for other things, so they can need to document a return result, but there isn't any support for that.

FR: Add support for documenting Starlark-defined transitions

Starlark-defined transitions are defined with the transition function, which does not have a doc parameter. The FR is to add that to Bazel and support it in stardoc.

it's hard to keep macro and rule documentation in sync

macros generally wrap commonly-used patterns of rules to make them easier to write. As such a very common pattern is to have the macro take a bunch of arguments and forward most of those verbatim or near-verbatim to various rules. The trouble is that when these patterns are combined with stardoc documentation, it ends up being necessary to repeat the same documentation for each rule attribute in the macro's docstring. If there were some way for the macro to refer to the rule attributes documentation, it would cut the docs that we need to write in ~half for these cases - or possibly even more when the same attribute is shared between several rules and many macros.

In practice, much of the macro documentation in the codebase I work in is actually incomplete because it's just too much effort to manually duplicate it all.

Transitive dependencies on @bazel_tools make it impossible to use Stardoc

The Skydoc issue bazelbuild/skydoc#166 is still causing me woes. The suggested solution seems to be to import the necessary dependencies explicitly:

stardoc(
    name = "st4",
    out = "st4.md",
    input = "st4.bzl",
    deps = [":refs"],
)

bzl_library(
    name = "refs",
    deps = ["@bazel_tools//tools:bzl_srcs"],
)

Unfortunately, Bazel 1.0.0. still fails:

ERROR: /path/rules_stringtemplate/stringtemplate/BUILD:20:12:
in deps attribute of bzl_library rule //stringtemplate:refs:
'@bazel_tools//tools:bzl_srcs' does not have mandatory providers: 'StarlarkLibraryInfo'

Am I doing something wrong?

This is the WORKSPACE definition I use:

git_repository(
    name = "io_bazel_stardoc",
    remote = "https://github.com/bazelbuild/stardoc.git",
    tag = "0.4.0",
)
load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories")
stardoc_repositories()

Allow a new "Generated Targets:" section in Docstring

It would be nice to be able to specify and generate some simple documentation for public targets generated by macros. In my head this looks something like:

def my_macro(name):
  """My macro summary.
  
  Args:
    name: The name of my macro.

  Generated Targets:
    :<name>: The main target description.
    <name>_secondary: The secondary target description.
  """
  my_rule(name = name)
  my_rule(name = "%s_secondary" % name)

As opposed to crawling through the macro to figure out documentation that needs to be generated for rules within. Mainly because it would could be annoying to figure out names that are string replaced and not generating documentation for rules that are implementation details.

Attribute / parameter links are broken with the markdown_tables format

markdown_tables format omits the destination of <a> tags in the signature

Better support for rules with wrapper macros

Many rules have a little wrapper around them to calculate default values. The best experience for the user is to see a single unified attribute list for the user visible part (the macro). But we also want to document the attributes on the rule itself. If we could link the macro and implementation in some way, we could

• highlight the fact in the docs. foo_library (implemented by foo_library_impl)
• show a unified attribute list without having to copy up to the macro (duplicates work) or (falsely) claim the default setting on the rule documentation.

Another potential win from semantically linking the wrapper and implementation is that we can have buildifier stop complaining about **kwargs style args, when we want to pass most from the wrapper to the rule untouched.

Better support for stardoc usage in another directory from the bzl files

It seems like it would make sense to put your stardoc() rules in a docs directory where you check in the generated files. But to do that you also have to export the *.bzl files if it has dependencies because the bzl_library will have more that one file in it. Ideally the rule would support a bzl_library as input where there is only one direct src entry, or it should support a raw string that isn't a label so the deps of the bzl_library could tell it which file to act on.

markdown_tables newline spacing is a bit off

For the markdown_tables output format, note that newline spacing of some table cells is overly aggressive.

This can be seen in stardoc's own documentation.
This:

        "semantic_flags": attr.string_list(
            doc = """
A list of canonical flags to affect Starlark semantics for the Starlark interpretter
during documentation generation. This should only be used to maintain compatibility with
non-default semantic flags required to use the given Starlark symbols.

For example, if `//foo:bar.bzl` does not build except when a user would specify
`--incompatible_foo_semantic=false`, then this attribute should contain
"--incompatible_foo_semantic=false".
""",

Turns into a table row:

| semantic_flags |  A list of canonical flags to affect Starlark semantics for the Starlark interpretter<br>during documentation generation. This should only be used to maintain compatibility with<br>non-default semantic flags required to use the given Starlark symbols.<br><br>For example, if <code>//foo:bar.bzl</code> does not build except when a user would specify<br><code>--incompatible_foo_semantic=false</code>, then this attribute should contain<br>"--incompatible_foo_semantic=false".   | List of strings | optional |

Which renders as:

Name	Description	Type	Mandatory
semantic_flags	A list of canonical flags to affect Starlark semantics for the Starlark interpretter during documentation generation. This should only be used to maintain compatibility with non-default semantic flags required to use the given Starlark symbols. For example, if //foo:bar.bzl does not build except when a user would specify --incompatible_foo_semantic=false, then this attribute should contain "--incompatible_foo_semantic=false".	List of strings	optional

Because of all the extra <br> tags.

We should perhaps only create line break tags when there are more than one sequential newlines.

Getting started example is broken for multiple files case

This doc page example no longer works after the change to Starlark that makes symbols not get re-exported automatically.

Improve argument type strings for compound types and macro args

Currently, with the exception of optional arguments and those named name or deps and perhaps a few more, all the types for Skylark macro arguments are Unknown.

I propose that skydoc support specifying argument types for macros using a {CurlyBrace} syntax. Here's an example:

def rat_check(name, srcs=[], format, visibility):
  """Runs Apache Rat license checks on the given source files.

  This rule runs [Apache Rat](http://creadur.apache.org/rat/) license checks on
  a given set of source files. Use `bazel build` to run the check.

  Args:
    name: A unique name for this rule.
    srcs: {List of Label} Source files to run the Rat license checks against.

      Note that the Bazel glob() function can be used to specify which source
      files to include and which to exclude.
    format: {String} The format to write the Rat check report in.
    visibility: {List of String} The visibility of this rule.
  """

Presumably, you'd have a handful of supported types as indicated by:
https://bazel.build/versions/master/docs/skylark/lib/skylark-builtin.html

writing_stardoc.md doesn't seem to say how to use markup within the doc string

Historically (skydoc) some areas had to be markdown, some had to be html. What is the final decision in stardoc?

Hopefully it can be all just basic markdown, and then the templates would know to always apply the same types of transforms for all cases to generate their final format.

Export full path of symbols in ModuleInfo

The ModuleInfo proto does not export the full path/label of the symbols, nor the other info protos. I'd like to write templates that automatically add load usage, e.g:

load('//foo/bar:baz.bzl', 'qux')

But the /foo/bar:baz.bzl part is not available for the template.

Update jar

It seems like there have been some error handling improvements upstream. With stardoc currently:

% bazel-out/host/bin/external/io_bazel_stardoc/stardoc/stardoc '--input=//bazel:module.bzl' '--workspace_name=lyftios' '--dep_roots=.' '--dep_roots=external/lyftios' '--output=bazel-out/darwin-fastbuild/bin/bazel/module-docs.raw'
Stardoc documentation generation failed: Starlark evaluation error

With the upstream jar:

% java -jar /private/var/tmp/_bazel_ksmiley/cdf42e3ebdb7335cbe8a7a6c07c7aed8/execroot/io_bazel/bazel-out/darwin-fastbuild/bin/src/main/java/com/google/devtools/build/skydoc/skydoc_deploy.jar '--input=//bazel:module.bzl' '--workspace_name=lyftios' '--dep_roots=.' '--dep_roots=external/lyftios' '--output=bazel-out/darwin-fastbuild/bin/bazel/module-docs.raw'
com.google.devtools.build.skydoc.SkydocMain$StarlarkEvaluationException: File external/build_bazel_rules_swift/swift/internal/swift_grpc_library.bzl imported '@rules_proto//proto:defs.bzl', yet external/rules_proto/proto/defs.bzl was not found, even at roots [., external/lyftios].
        at com.google.devtools.build.skydoc.SkydocMain.recursiveEval(SkydocMain.java:467)
        at com.google.devtools.build.skydoc.SkydocMain.recursiveEval(SkydocMain.java:457)
        at com.google.devtools.build.skydoc.SkydocMain.recursiveEval(SkydocMain.java:457)
        at com.google.devtools.build.skydoc.SkydocMain.eval(SkydocMain.java:325)
        at com.google.devtools.build.skydoc.SkydocMain.main(SkydocMain.java:228)
Caused by: java.nio.file.NoSuchFileException: external/rules_proto/proto/defs.bzl
        at com.google.devtools.build.skydoc.SkydocMain.getInputSource(SkydocMain.java:501)
        at com.google.devtools.build.skydoc.SkydocMain.recursiveEval(SkydocMain.java:443)
        at com.google.devtools.build.skydoc.SkydocMain.recursiveEval(SkydocMain.java:457)
        ... 4 more
Stardoc documentation generation failed: File external/build_bazel_rules_swift/swift/internal/swift_grpc_library.bzl imported '@rules_proto//proto:defs.bzl', yet external/rules_proto/proto/defs.bzl was not found, even at roots [., external/lyftios].

Is there a process for updating this?