Better rule documentation

useblocks / sphinx-bazel

Sphinx extension to read bazel files

http://sphinx-bazel.readthedocs.io/en/latest/

Apache License 2.0

11 stars 4 forks source link

Better rule documentation #9

Closed danwos closed 5 years ago

danwos commented 5 years ago

Rule documentation suppose to have:

Rule name
Rule invocation
Rule docstring
Rule implementation reference
Attributes list: Parameters, Type, Docstring

danwos commented 5 years ago

I'm not sure if rule invocation can be documented, as this information is nothing from the rule itself but from other BUILD files or based on bazel internal calculation.

danwos commented 5 years ago

So has far as I have understood:

name, docstring and implementation reference are already part of documentation
invocation may be really hard to get. Lets see what I can do here
Attributes list is open. But should be doable

For Attribute list I think an Attribute must get its own place in the bazel domain. So .. bazel:attribute:: //main:target:rule:attribute

Reason, the documentation of an Attribute can be complex and contain rst-content as well. So putting it inside the head of a rule description may destroy the layout if e.g the docs is longer than x chars or even contains an image.

apekter commented 5 years ago

For the attribute I agree it makes sense to create bazel:attribute.

In case of the invocation I disagree that it is hard to get once you already have the attributes of the rule. Example:

my_rule = rule(
    implementation = _my_rule_impl,
    attrs = {
        "srcs" : attr.string(
            default="foo",
            doc = "Source files.",
        ),
        "deps" : attr.string(
            default="bar",
            doc = "Dependencies of this target.",
        ),
    }
)

The invocation is:

my_rule(srcs, deps)

danwos commented 5 years ago

Ahh got it. You do not need the calls of the current rule by other rules/bzl-files, but just the "call-printing" containing name and attributes. Okay, this is easily possible.